# enablebanking/open_banking_eidas_broker architecture

> Architecture diagram of the GitHub repository enablebanking/open_banking_eidas_broker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enablebanking/open_banking_eidas_broker
- Repository: https://github.com/enablebanking/open_banking_eidas_broker

## Overview

##### Project type and purpose
- This is a containerized, full-stack API microservice (“Open Banking eIDAS broker”) implemented in Python 3.11 using FastAPI.
- It exposes three REST endpoints (`/sign`, `/makeRequest`, `/health`) over mTLS, offloading signature generation and mutually authenticated HTTP calls to downstream ASPSP (Account Servicing Payment Service Provider) APIs.

##### File structure
- Top level:
- Dockerfile, run.sh, run.py, nginx.conf → container build & runtime
- openapi.json → API contract
- requirements.txt → Python deps
- trusted_aspsps_certs/ → built-in ASPSP CA certs
- app/ → service code & tests
- examples/ → usage examples
- .github/workflows/ → CI (test, image-scan)
- app/ contains:
- main.py (FastAPI app & routing)
- server_platform.py (ServicePlatform: `sign_with_key`, `make_request`)
- key_loader.py (abstraction for loading certs & keys from FS or ENV)
- models.py (Pydantic request/response schemas)
- tests/ → unit & integration tests
- Deployment config: nginx.conf for mTLS frontend, Gunicorn/Uvicorn worker, Docker build binds volumes for broker TLS and open banking certs.

##### README for additional insights
- Describes end-to-end flows:
a. Client calls POST /sign → broker signs data with a QSealC cert
b. Client calls POST /makeRequest → broker opens mTLS connection to ASPSP using QWAC cert
c. Certificates & keys are never shipped to the client; loaded server-side
- Outlines certificate generation & mounting strategy, environment variables for encrypted keys, custom trust store overrides.
- CI pipelines enforce tests and image scanning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client\n(Aggregation SDK)"]:::network
    ExamplesScript["example.py"]:::network
    click ExamplesScript "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/examples/example.py"
    ExampleKey["example.key"]:::network
    click ExampleKey "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/examples/example.key"
    Client -->|"mTLS POST /sign, /makeRequest, /health"| Nginx

    %% Broker Container
    subgraph "Broker Container" 
        direction TB
        Nginx["Nginx Reverse Proxy\n(mTLS Frontend)"]:::compute
        click Nginx "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/nginx.conf"
        FastAPI["FastAPI App\n(Gunicorn+Uvicorn)"]:::compute
        click FastAPI "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/app/main.py"
        Contract["API Contract\n(openapi.json)"]:::infra
        click Contract "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/openapi.json"

        subgraph "Application Logic"
            direction TB
            ServicePlatform["ServicePlatform\n(sign_with_key, make_request)"]:::compute
            click ServicePlatform "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/app/server_platform.py"
            KeyLoader["Key Loader"]:::compute
            click KeyLoader "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/app/key_loader.py"
            Models["Pydantic Models"]:::compute
            click Models "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/app/models.py"
        end

        Crypto["Cryptography Lib\n(OpenSSL via cryptography)"]:::infra

        subgraph "TLS & Cert Volumes"
            direction TB
            Vol_BrokerTLS["Broker TLS Volume\n(/app/broker_tls)"]:::storage
            Vol_OpenBank["Open Banking Certs\n(/app/open_banking_certs)"]:::storage
            Vol_TrustedCA["Trusted CA Certs\n(/app/trusted_ca_certs)"]:::storage
            click Vol_TrustedCA "https://github.com/enablebanking/open_banking_eidas_broker/tree/master/trusted_aspsps_certs/"
        end
    end

    %% External ASPSP
    subgraph "External ASPSP APIs" 
        ASPSP["ASPSP Endpoint\n(mTLS)"]:::network
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        direction TB
        GH_Tests["GitHub Actions: Run Tests"]:::ci
        click GH_Tests "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/.github/workflows/test.yml"
        GH_Scan["GitHub Actions: Image Scanning"]:::ci
        click GH_Scan "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/.github/workflows/image-scanning.yml"
        DockerBuild["Docker Build & Runtime"]:::infra
        click DockerBuild "https://github.com/enablebanking/open_banking_eidas_broker/tree/master/Dockerfile"
        click DockerBuild "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/run.sh"
        click DockerBuild "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/run.py"
        Requirements["Python Dependencies"]:::infra
        click Requirements "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/requirements.txt"
        click Requirements "https://github.com/enablebanking/open_banking_eidas_broker/blob/master/app/tests/requirements.txt"
    end

    %% Data Flows
    Nginx -->|"HTTP Proxy"| FastAPI
    FastAPI -->|"sign_with_key()"| ServicePlatform
    FastAPI -->|"make_request()"| ServicePlatform
    ServicePlatform -->|"load_certs_keys"| KeyLoader
    KeyLoader --> Vol_BrokerTLS
    KeyLoader --> Vol_OpenBank
    KeyLoader --> Vol_TrustedCA
    KeyLoader --> Crypto
    ServicePlatform --> Crypto
    ServicePlatform -->|"mTLS HTTP"| ASPSP
    ASPSP -->|"response"| ServicePlatform
    ServicePlatform --> FastAPI
    FastAPI -->|"HTTP Response"| Nginx
    Nginx -->|"mTLS Response"| Client

    %% CI/CD to Docker
    GH_Tests --> DockerBuild
    GH_Scan --> DockerBuild
    DockerBuild --> BrokerContainer

    %% Styles
    classDef network fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef ci fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
