# System overview

## C4 — Context (Level 1)

```mermaid
flowchart TB
    User[Bank user<br/>analyst / engineer / GRC]
    Auditor[External auditor<br/>read-only]
    LLM[LLM gateway<br/>your perimeter]
    LF[Langfuse<br/>optional]
    GHCR[(GHCR<br/>signed images)]

    Edge[Edge<br/>AI evaluation platform]

    User -->|HTTPS, JWT| Edge
    Auditor -->|read-only | Edge
    Edge -->|chat/completions| LLM
    Edge -.->|traces/spans| LF
    GHCR -->|deployed from| Edge
```

## C4 — Container (Level 2)

```mermaid
flowchart TB
    subgraph "User"
        Browser[Browser]
    end

    subgraph "Edge container (1 image)"
        Nginx[Nginx<br/>:8080]
        UI[React + Vite SPA<br/>16 pages]
        API[FastAPI backend<br/>:8000<br/>27 services, 17 routers]
        MCP[OpsKiln MCP<br/>:8180]
        PB[(PocketBase<br/>:8090<br/>15 collections)]
    end

    subgraph "Your perimeter"
        Gateway[LLM gateway<br/>OpenAI / Anthropic / AI Hub]
    end

    subgraph "Optional sidecar"
        Langfuse[Langfuse v3]
    end

    Browser -->|HTTPS| Nginx
    Nginx -->|static| UI
    Nginx -->|/api/*| API
    Nginx -->|/pb/*| PB
    API --> PB
    API -->|JSON-RPC| MCP
    MCP --> PB
    API -->|cert auth / bearer| Gateway
    API -.->|traces| Langfuse
```

## The six-repo split

```mermaid
flowchart LR
    subgraph "Source"
        APP[edge-app<br/>product source]
        WF[edge-workflows<br/>reusable CI]
        GOV[edge-governance<br/>docs + policy]
    end

    subgraph "Marketing"
        LAND[edge-landing<br/>Astro site]
        DEMOS[edge-demos<br/>buyer proof packs]
    end

    subgraph "Ops"
        INFRA[edge-infra<br/>dev/staging/prod]
        GHCR[(GHCR<br/>edge-app:vX.Y.Z)]
    end

    APP -->|tag-driven release| GHCR
    GHCR -->|consumed by| INFRA
    WF -.->|workflow_call| APP
    WF -.->|workflow_call| INFRA
    GOV -->|owns rules for| APP
    GOV -->|owns rules for| INFRA
    LAND -->|points at| GOV
    DEMOS -->|uses| APP
```

| Repo              | Owns                                                            | Does **not** own                            |
| ----------------- | --------------------------------------------------------------- | ------------------------------------------- |
| `edge-app`        | Source code, Dockerfile, app CI, release workflow               | Per-env manifests, K8s YAML, secrets wiring |
| `edge-infra`      | dev/staging/prod manifests, on-prem mirror, observability stack | Application source, Dockerfile              |
| `edge-workflows`  | Reusable GitHub Actions workflows                               | Repo-specific overrides                     |
| `edge-governance` | Docs, policies, banking gates, audit material                   | Code                                        |
| `edge-landing`    | Marketing site (`edge.nyami.fr`)                                | Product UI                                  |
| `edge-demos`      | Buyer-facing datasets and demo scripts                          | Production data                             |

## Layer responsibilities

| Layer             | Components                                                                                                      | Source                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Frontend**      | 16 pages, 23 service modules, React Flow 11, Tailwind CSS v4, `@mcp-ui/client`                                  | `edge-app/web/`                        |
| **Backend**       | FastAPI 0.121+, 8 action handlers, 31 services, flow\_executor.py (topological sort)                            | `edge-app/backend/`                    |
| **Database**      | PocketBase 0.36.4, 15 collections (datasets, evaluation\_runs, metrics, ai\_reports, flows, scheduled\_jobs, …) | `edge-app/pocketbase/`                 |
| **MCP**           | OpsKiln PB adapter (streamable HTTP), MCPClientService (JSON-RPC 2.0), PB MCP Server (fastmcp)                  | `edge-app/opskiln-pocketbase-adapter/` |
| **Observability** | Optional Langfuse v3 stack                                                                                      | `edge-app/langfuse/`                   |

## Boundary contract (app ↔ infra)

The rule of thumb: **a change that requires a code review of business logic belongs in app; a change that only retunes a deployment knob belongs in infra.**

| Surface                                         | Belongs in   | Why                   |
| ----------------------------------------------- | ------------ | --------------------- |
| `Dockerfile`, source, unit/integration tests    | `edge-app`   | Tied to source layout |
| `.github/workflows/ci.yml`, `release.yml`       | `edge-app`   | App-side CI           |
| K8s manifests, Helm values, Terraform           | `edge-infra` | Per-env deployment    |
| On-prem mirror scripts                          | `edge-infra` | Bank-side delivery    |
| Observability stack (`observability/langfuse/`) | `edge-infra` | Sidecar to deployment |

Cross-reference: a CI guard in `edge-app` should block infra-looking diffs from landing in app. See [Banking Readiness Gate 03](/banking-readiness/gate-03-cicd-security.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edge.nyami.fr/architecture/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.