docs: update README, index, architecture, and glossary to include portal...

**Implementing a component**

1. Read [platform/architecture.md](platform/architecture.md) for the end-to-end mental model.

2. Open the component folder ([oeg/](oeg/), [srm/](srm/), [fm/](fm/), [tf-sdk/](tf-sdk/)) via its `index.md`.

2. Open the component folder ([oeg/](oeg/), [srm/](srm/), [fm/](fm/), [tf-sdk/](tf-sdk/), [portal/](portal/)) via its `index.md`.

3. Follow architecture → interface contract → persistence model → flow walk-throughs in that order.

4. When a spec cites an ADR, read the decision record for the rationale behind the rule.

| [srm/](srm/) | Service Resource Manager — orchestration and inventory |

| [fm/](fm/) | Federation Manager — cross-operator EWBI federation |

| [tf-sdk/](tf-sdk/) | Transformation Function SDK — vendor adapters inside SRM |

| [portal/](portal/) | Portal — developer portal and admin console |

| [decisions/](decisions/) | Architecture Decision Records |

| [external-specs/](external-specs/) | Vendored third-party API definitions |

| [archive/](archive/) | Superseded working documents |

* [SRM — Service Resource Manager](srm/) - internal orchestration and inventory: architecture, contracts, persistence, canonical schemas, worked examples

* [FM — Federation Manager](fm/) - cross-operator (E/WBI) federation: three-part spec from overview to delivery

* [TF-SDK — Transformation Function SDK](tf-sdk/) - vendor adapter library inside SRM: three-part spec from overview to delivery

* [Portal](portal/) - developer portal and admin console: three-part spec from overview to delivery

# Records

| Topology hiding for federation responses | FM | SRM, TF-SDK |

| Federation usage records for operator charging integration | FM | SRM |

| Self-service developer UI | Portal | OEG |

| Admin console for operators | Portal | OEG, SRM |

| Admin console for operators | Portal | OEG |

---

**Flow:**

1. Developer logs in via SSO (OIDC with Keycloak).

2. Developer browses API catalog (Portal fetches from OEG, which proxies SRM).

3. Developer creates an application (Portal BFF calls OEG/CAPIF for credential generation).

4. Developer receives OAuth2 client credentials.

5. Developer selects API products and accepts terms.

6. Developer makes first API call using credentials.

3. Developer creates an API client for API products they hold (the portal registers a Keycloak client, ADR-0066).

4. Developer receives OAuth2 client credentials; the secret is shown once.

5. Developer makes first API call using credentials.

**Priority:** Must

**What it is:** The self-service web interface for developers and operators. Developers discover APIs, register applications, manage credentials, and view analytics. Operators publish API products, manage federation, and monitor platform health.

**What it is not:** The Portal does not route API traffic — OEG does. It does not store master catalog or inventory data — it reads from OEG and SRM. It does not manage user identities — Keycloak does.

**What it is not:** The Portal does not route API traffic — OEG does. It does not store master catalog or inventory data — it reads from OEG. It does not manage user identities — Keycloak does.

**Key design patterns:**

- **Backend-for-Frontend (BFF):** The Portal BFF aggregates data from multiple backend APIs (TMF catalogs, metrics, IAM) into single UI-optimized responses. The frontend never calls backend APIs directly.

- **BFF Token Handler:** The browser never receives raw JWTs. The BFF holds tokens and issues encrypted HTTP-only cookies.

- **GraphQL:** A single Portal page often needs data from 3+ backend APIs. GraphQL lets the BFF stitch these into one query.

- **Backend-for-Frontend (BFF):** One container: a FastAPI backend serves the React app and its own API, and forwards calls to OEG and AI² as the user. The frontend never calls backend APIs directly (ADR-0064).

- **BFF Token Handler:** The browser never receives a token. The backend keeps the tokens in its database, encrypted with a key only the session cookie holds (ADR-0065).

**Reference:** Portal Spec

**Reference:** [portal/overview-and-architecture.md](/portal/overview-and-architecture.md), [portal/requirements-and-design.md](/portal/requirements-and-design.md), [portal/implementation-and-delivery.md](/portal/implementation-and-delivery.md)

### AI Service — AI Agent + RAG Orchestrator

| OEG | Process alive | PostgreSQL + DataBus connectivity |

| SRM | Process alive | PostgreSQL + DataBus connectivity |

| FM | Process alive | PostgreSQL + DataBus connectivity |

| Portal BFF | Process alive | OEG reachable + IAM reachable |

| Portal | Process alive | Database reachable |

### Key Metrics (Phase 2)

│                                                  │

│  ┌──────────┐  ┌─────────┐  ┌──────────────┐   │

│  │    FM    │  │  Portal │  │   Keycloak   │   │

│  │ (FastAPI)│  │ (Next.js│  │              │   │

│  │  :8082   │  │  + BFF) │  │              │   │

│  │ (FastAPI)│  │ (FastAPI│  │              │   │

│  │  :8082   │  │ + React)│  │              │   │

│  │          │  │         │  │              │   │

│  └──────────┘  └─────────┘  └──────────────┘   │

│                                                  │

| `core` | PostgreSQL, Redis, NATS, Keycloak, Nginx |

| `platform` | OEG, SRM (with TF-SDK), FM, Artefact Manager |

| `ai` | AI Service, MCP Server, Qdrant |

| `portal` | Portal (Next.js dev server) + BFF |

| `portal` | Portal (backend serving the React app) |

| `all` | Everything |

### Scaling Strategy

| SRM | Horizontal (stateless pods, shared PostgreSQL) | Database write throughput for order/inventory |

| TF-SDK | Scales with SRM (embedded library) | SBI HTTP call latency |

| FM | Horizontal (stateless FastAPI pods, shared PostgreSQL) | EWBI routing table lookup |

| Portal | Frontend; BFF horizontal | BFF concurrent connections |

| Portal | Horizontal (one container; sessions in shared PostgreSQL) | Backend concurrent connections |

---

| Library vs. service (TF-SDK) | Library (inside SRM) | Eliminates network-hop latency. Translation is stateless — no independent lifecycle needs. |

| Redis-backed correlation in TF-SDK vs. stateless TF-SDK | Stateless TF-SDK | Simpler to test and maintain. SRM already manages Redis. One Redis dependency is better than two. |

| Federation usage collection vs. charging-system interaction | Durable async usage records first | Request-path latency must not depend on operator-specific charging/wholesale systems; downstream charging policy may still select event/session models. |

| Custom Portal vs. Backstage.io | Custom Next.js build | Maximum control over branded NaaS monetization workflows. |

| Custom Portal vs. Backstage.io | Custom React app served by a FastAPI backend (ADR-0064) | Maximum control over branded NaaS monetization workflows. |

---

| 2.0 | 2026-09-01 | Ownership Matrix corrected: RFC 7807 problem+json construction for SBI refusals is SRM's, not TF-SDK's. `can_serve_target` interface listing updated to the tri-state answer (ADR-0040) and TF-SDK-owned adapter factory (ADR-0041). |

| 2.0 | 2026-09-04 | Component Boundary Matrix updated: operator-triggered federation establishment is proxied through OEG (`command.fm.*`, ADR-0043); Edge Cloud Zone locality determination for deployment targets moves from OEG to SRM as an interim layer pending a future runtime-coordinator component (ADR-0044). Placement-decisions row absorbs the new locality row (was listing an inconsistent Not-Owner set); federation admin CRUD folded into the existing EWBI row instead of a redundant new one; Not-Owner columns corrected to name the passive consumer (FM) rather than an unrelated component. |

| 2.0 | 2026-10-04 | Roles table adds `platform-admin` and product grants: a product role gates each product's CAMARA scopes, new users hold no product by default, tenancy is the `organization` claim, development mode is localhost only (ADR-0048). |

| 2.0 | 2026-10-09 | Portal matches the built portal (ADR-0064 to ADR-0066): one container with a FastAPI backend, no GraphQL, cookie-keyed sessions, API clients registered in Keycloak (UC-OOP-08), readiness checks the database; links the new `portal/` spec. |

| **CHF** | Charging Function — 3GPP component (TS 32.290/291) handling convergent online/offline charging. Backend target for TF-SDK's future Charging domain. |

| **UDM** | Unified Data Management — 3GPP component (TS 29.503) managing subscriber data, identity resolution, and access authorization. Backend target for TF-SDK's future Consent domain. |

| **ICM** | Identity and Consent Management — CAMARA specification defining how subscriber consent is obtained and validated, including three-legged and two-legged token models. |

| **CAPIF** | Common API Framework — 3GPP architecture (TS 23.222) for discovering, publishing, and managing service APIs. OEG implements CAPIF-like functions for API discovery and credential management. |

| **CAPIF** | Common API Framework — 3GPP architecture (TS 23.222) for discovering, publishing, and managing service APIs. OOP does not implement it: API discovery is the portal's catalog, and API credentials are Keycloak clients the portal registers (ADR-0066). |

| **CDR** | Charging Data Record — standardized record of a chargeable event, used for billing and inter-operator settlement. |

## Interfaces

| Term | Meaning |

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

| **API product** | What OEG offers and an application is entitled to: a published API with its policy and quota (OEG's API Product Catalog). In Release 2 there are four, each one CAMARA API (`edge-application-management`, `quality-on-demand`, `location-retrieval`, `traffic-influence`); quota and policy are not enforced yet, and access is enforced through the product's fixed set of CAMARA scopes (ADR-0048) |

| **API client** | Credentials a developer creates in the portal so their own software can call OEG: a client-credentials Keycloak client limited to the API products the developer holds (ADR-0066) |

| **App Provider** | The upstream client using OEG's northbound APIs |

| **Product grant** | Permission for a user or client to use one API product, enforced as a product role on the `oeg` client that gates the product's CAMARA scopes (ADR-0048) |

| **Callback** | An outbound CloudEvent (`application/cloudevents+json`) from OEG to an App Provider's registered sink when an async operation reaches a terminal state; authenticated with `Authorization: Bearer` using the request's `sinkCredential` (ADR-0008). `operationId` is never included in the callback payload. |

| 2.0 | 2026-09-01 | Placement, Network Domain, and Control path binding entries note the device-targeted control-path-probe exception (no zone/domain pin; adapter probing, ADR-0038/ADR-0040) and TF-SDK's adapter factory (ADR-0041). |

| 2.0 | 2026-10-04 | API product entry names the four products; new Product grant entry; Subscription marked reserved for quota and validity (ADR-0048). |

| 2.0 | 2026-10-05 | API product entry defined as what OEG offers (API, policy, quota), not as its scopes; scopes are how Release 2 enforces it (ADR-0048). |

| 2.0 | 2026-10-09 | New API client entry; CAPIF entry says OOP does not implement it (ADR-0066). |