docs: describe the FastAPI app in the README

# Open Exposure Gateway

The **Open Exposure Gateway (OEG)** is a Python web service implementation. It implements the **Open Exposure Gateway** role of the Operator Platform, defined by the [GSMA Operator Platform Group (OPG)](https://www.gsma.com/solutions-and-impact/technologies/networks/gsma-operator-platform-group-september-2024-publications/).

The **Open Exposure Gateway (OEG)** implements the **Open Exposure Gateway** role of the Operator Platform, defined by the [GSMA Operator Platform Group (OPG)](https://www.gsma.com/solutions-and-impact/technologies/networks/gsma-operator-platform-group-september-2024-publications/).

### Overview

OEG is a FastAPI service (`open_exposure_gateway.main:app`). It serves the northbound CAMARA APIs, checks the caller's Keycloak token, and hands the work to the Service Resource Manager (SRM): over the DataBus (NATS) for long-running work, over HTTP for reads and synchronous queries. Federation lifecycle calls are proxied to the Federation Manager.

This server was generated by the [swagger-codegen](https://github.com/swagger-api/swagger-codegen) project.

It uses the [Connexion](https://github.com/zalando/connexion) library on top of Flask.

It propagates requests to the [ OP service resource manager](https://github.com/OpenOperatorPlatform/service_resource_manager), as configured in the `.env`.

OEG implements the **Northbound CAMARA APIs** for application providers to interact with different infrastructures, including:

- Application metadata lifecycle management (registering, retrieving, deleting apps)

- Application instantiation management (instantation, and termination)

- Federation lifecycle APIs for the operator to set up and manage federations with partner operator platforms (proxied to the Federation Manager)

OEG acts as a middleware layer between the CAMARA APIs and the Service Resource Manager (SRM), by enabling a common exposure of heteregeneous infrastructure resources.

<br>

| Edge Cloud Management API  | Federation Lifecycle API (GSMA OPG.04 v1.4.0) | Network Exposure API  (QoD & Traffic Influence)|

| Edge Application Management | Federation Lifecycle API (GSMA OPG.04 v1.4.0) | Network APIs (QoD, Traffic Influence, Location Retrieval) |

| ------------- | ------------- | ------------- |

| Application Metadata registration  | Create one direction federation   | Create QoD Session |

| App Metadata Removal  | Retrieve details about federation with the partner OP  | Remove QoD Session  |

| App Metadata Retrieval  | Retrieve the existing federationContextId with partner  | Retrieve QoD Session  |

| Application Instantiation  | Remove existing federation with partner OP | Create TrafficeInfluence Resource  |

| Application Instance Retrieval | List the zones the partner OP offers | Remove TrafficeInfluence Resource  |

| Application Instance Removal  | Subscribe to partner OP zones | Retrieve TrafficeInfluence Resource  |

| Application registration, retrieval and removal | Create one direction federation | Create, retrieve and remove a QoD session |

| Application instantiation, retrieval and removal | Retrieve details about federation with the partner OP | Create, list, retrieve and remove a Traffic Influence resource |

| Multi-zone deployments | Retrieve the existing federationContextId with partner | Create a Traffic Influence resource for one device (`POST /traffic-influence-devices`) |

| Edge cloud zones | Remove existing federation with partner OP | Retrieve a device location (`POST /retrieve`) |

|  | List the zones the partner OP offers |  |

|  | Subscribe to partner OP zones |  |

|  | Retrieve details of a subscribed partner zone |  |

|  | Unsubscribe from a partner zone |  |

OEG forwards each request unchanged to the Federation Manager's matching `/internal/...` endpoint

and relays its answer; every error on these routes is a GSMA `application/problem+json` `ProblemDetails`.

## Deployment

OEG can be deployed in a Kubernetes cluster by executing the file _oeg-deployment.yaml_ located in the root folder. This file will create a OEG Deployment resource and its supporting native K8s Service. The following table contains the necesssary environment variables for the Kubernetes adapter.

OEG is deployed with the platform Helm chart (`oop-platform-chart` in the helm repository). Settings are

environment variables read by `src/open_exposure_gateway/core/config.py`; `.env.example` lists every one

with its default. The ones you most often change:

| **Variable**                | **Description**                                             |

|-----------------------------|-------------------------------------------------------------|

| `SRM_HOST`                  | Base URL of the Service Resource Manager                   |

| `SRM_SETTINGS__BASE_URL`    | Base URL of the Service Resource Manager (default `http://localhost:8081`) |

| `POSTGRESQL_SETTINGS__URL`  | OEG's database |

| `NATS_SETTINGS__URL`        | The DataBus |

| `KEYCLOAK_SETTINGS__ISSUER`, `KEYCLOAK_SETTINGS__JWKS_URL`, `KEYCLOAK_SETTINGS__AUDIENCE` | The Keycloak realm whose tokens OEG accepts |

| `FM_SETTINGS__BASE_URL`     | Federation Manager's internal API, on its internal port (default `http://localhost:8083`) |

| `FM_SETTINGS__TIMEOUT`      | Seconds to wait for Federation Manager (default `30`) |

### Running locally

Copy `.env.example` to `.env` and uncomment what you need to change. Then, from the root directory:

You can also run the OEG outside of k8s environment:

Before running the server you need to `mv env.sample .env` and update variables to properly link to a running OP service resource manager instance.

To run the server, please execute the following from the root directory:

Using uv:

```bash

# run the server as module - uv will automatically take care of any dependencies installation

uv run edge_cloud_management_api

uv run uvicorn open_exposure_gateway.main:app --port 8080

```

and open your browser to the OpenAPI documentation: `http://127.0.0.1:8080/docs/`

and open the OpenAPI documentation at `http://127.0.0.1:8080/docs`. `make run` starts the same app with

reload on uvicorn's default port 8000.

### Testing

To launch the integration tests, use tox:

```bash

uv run tox

make test         # unit and integration tests

make conformance  # CAMARA conformance suite

make precommit    # lint, format and the other pre-commit hooks

make type         # mypy

```

### CAMARA specs and conformance testing

```bash

# building the image

docker build -t edge_cloud_management_api .

docker build -t open-exposure-gateway .

# starting up a container

docker run -p 8080:8080 --env-file ./.env edge_cloud_management_api

docker run -p 8080:8080 --env-file ./.env open-exposure-gateway

```