# minvws/nl-rdo-max architecture

> Architecture diagram of the GitHub repository minvws/nl-rdo-max, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minvws/nl-rdo-max
- Repository: https://github.com/minvws/nl-rdo-max

## Overview

- Core Application – Represent the MAX core engine (started through app/application.py and app/main.py) that orchestrates the authentication flow.
- Dependency Injection & Configuration – Include the “dependency_injection” module which manages the configuration, service initialization, and encryption services. Note the separation of configuration (config.py) and container management (container.py).
- Service Layer – Represent the various “services” modules. This includes authentication handlers (loginhandler submodule with multiple authentication_handler implementations), token factories (response_factory), encryption services (jwe, jwt, RSA, xed25519, etc.), and SAML identity provider services.
- External Providers – Identify the providers in “providers” which are concrete implementations for different authentication protocols (e.g., oidc_provider, saml_provider, digid_mock_provider, pyop_provider). Also capture that MAX interacts with external systems like DigiD, TVS, and the nl-uzi-login-controller.
- Storage & Caching – Include the storage system (especially under app/storage/redis) which uses Redis for authentication caching. This is key for tracking states (like random state and user limits).
- Encryption/Key Management – Outline the “services/encryption” module that handles JWT signing, JWE encryption, and key generation/management as described in the README. Include a note on the presence of both Ed25519 and X25519 keys.
- Mock Environment – Since the system supports a DigiD mock for development (if not in production) and supports a “mock” login method, include a component that represents this “DigiD Mock” flow.
- Rate Limiter – Represent the rate limiter mechanism found in app/misc/rate_limiter.py that can route traffic to a secondary (“overflow”) identity provider when necessary.
- External and Third-party Integration – Optionally include external systems like the NL UZI Login Controller, a separate identity provider’s backends, and any external registers from which BSN properties are retrieved.

##### Relationships and Interactions
- Flow from the authentication endpoints (in routers) to appropriate service handlers (from loginhandler and auth handlers) that engage the providers.
- That after user authentication, MAX retrieves or validates tokens either by contacting an external TVS or handling SAML flows internally.
- Data flow between the authentication services, the encryption layer (for signing or encrypting JWT token data), and the storage/cache (Redis).
- If desired, include Docker/Container references (e.g., through docker-compose.yml) as a surrounding infrastructure context, noting that these containers are meant for development.

##### Architectural Patterns & Design Principles
- The project follows a modular, layered architecture where responsibilities are clearly separated (e.g., routing, service logic, data models, and providers).
- It uses dependency injection to decouple configuration and service instantiation.
- The design emphasizes plug-ability: different authentication flows (OIDC vs. SAML vs. DigiD mock) are handled by separate providers and service implementations.
- It employs an external caching mechanism (Redis) for stateful operations and rate limiting.
- To call out how the PKCE OIDC flow is integrated by showing its specific endpoints and the code snippet verification process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client (Browser/OIDC Client)"]:::client

    %% API Routers
    subgraph "API Routers"
        OIDC_Router["OIDC Router"]:::router
        SAML_Router["SAML Router"]:::router
        DigiD_Mock_Router["DigiD Mock Router"]:::router
        Docs_Router["Docs Router"]:::router
        Misc_Router["Misc Router"]:::router
    end

    %% Core Application Layer
    subgraph "Core Application"
        Core_App["Core Application"]:::core
        Dependency_Injection["Dependency Injection & Configuration"]:::di
        Data_Models["Data Models"]:::models
    end

    %% Service Layer
    subgraph "Service Layer"
        Login_Handler["Login Handler"]:::service
        Mock_Auth_Handler["Mock Authentication Handler"]:::service
        Response_Factory["Response Factory"]:::service
        SAML_Service["SAML Identity Provider Service"]:::service
        Encryption_Service["Encryption/Key Management"]:::encryption
        Rate_Limiter["Rate Limiter"]:::ratelimiter
    end

    %% External Providers
    subgraph "External Providers"
        OIDC_Provider["OIDC Provider"]:::provider
        SAML_Provider["SAML Provider"]:::provider
        DigiD_Provider["DigiD Provider"]:::provider
        Pyop_Provider["PyOP Provider"]:::provider
        External_IDP["External IDP/TVS & NL UZI"]:::provider
    end

    %% Storage & Caching
    subgraph "Storage & Caching"
        Redis_Cache["Redis Cache"]:::storage
    end

    %% Connections from Client to Routers
    Client -->|"AuthRequest"| OIDC_Router
    Client -->|"AuthRequest"| SAML_Router
    Client -->|"AuthRequest"| DigiD_Mock_Router
    Client -->|"DocsAccess"| Docs_Router
    Client -->|"MiscRequests"| Misc_Router

    %% Routers call Core Application
    OIDC_Router -->|"RouteRequest"| Core_App
    SAML_Router -->|"RouteRequest"| Core_App
    DigiD_Mock_Router -->|"RouteRequest"| Core_App
    Docs_Router -->|"RouteRequest"| Core_App
    Misc_Router -->|"RouteRequest"| Core_App

    %% Core Application interactions
    Core_App -->|"Orchestrates"| Login_Handler
    Core_App -->|"Orchestrates"| Response_Factory
    Core_App -->|"Uses"| Data_Models
    Dependency_Injection -->|"InjectsConfig"| Core_App
    Dependency_Injection -->|"InjectsConfig"| Login_Handler
    Dependency_Injection -->|"InjectsConfig"| Encryption_Service

    %% Service Layer flows
    Login_Handler -->|"ProcessAuth"| Encryption_Service
    Login_Handler -->|"ProcessAuth"| SAML_Service
    Login_Handler -->|"ProcessAuth"| OIDC_Provider
    Login_Handler -->|"ProcessAuth"| SAML_Provider
    Login_Handler -->|"ProcessAuth"| DigiD_Provider
    Login_Handler -->|"ProcessAuth"| Pyop_Provider
    Login_Handler -->|"ChecksRate"| Rate_Limiter
    Rate_Limiter -->|"RoutesTo"| External_IDP
    Encryption_Service -->|"Encrypt/Sign"| Redis_Cache
    Response_Factory -->|"BuildsToken"| Encryption_Service
    DigiD_Mock_Router -->|"DirectMockFlow"| Mock_Auth_Handler

    %% Click Events for Core Application Layer
    click Core_App "https://github.com/minvws/nl-rdo-max/blob/main/app/application.py"
    click Core_App "https://github.com/minvws/nl-rdo-max/blob/main/app/main.py"

    click Dependency_Injection "https://github.com/minvws/nl-rdo-max/blob/main/app/dependency_injection/config.py"
    click Dependency_Injection "https://github.com/minvws/nl-rdo-max/blob/main/app/dependency_injection/container.py"

    click Data_Models "https://github.com/minvws/nl-rdo-max/tree/main/app/models"

    %% Click Events for API Routers
    click OIDC_Router "https://github.com/minvws/nl-rdo-max/blob/main/app/routers/oidc_router.py"
    click SAML_Router "https://github.com/minvws/nl-rdo-max/blob/main/app/routers/saml_router.py"
    click DigiD_Mock_Router "https://github.com/minvws/nl-rdo-max/blob/main/app/routers/digid_mock_router.py"
    click Docs_Router "https://github.com/minvws/nl-rdo-max/blob/main/app/routers/docs_router.py"
    click Misc_Router "https://github.com/minvws/nl-rdo-max/blob/main/app/routers/misc_router.py"

    %% Click Events for Service Layer
    click Login_Handler "https://github.com/minvws/nl-rdo-max/tree/main/app/services/loginhandler"
    click Response_Factory "https://github.com/minvws/nl-rdo-max/blob/main/app/services/response_factory.py"
    click SAML_Service "https://github.com/minvws/nl-rdo-max/tree/main/app/services/saml"
    click Encryption_Service "https://github.com/minvws/nl-rdo-max/tree/main/app/services/encryption"
    click Mock_Auth_Handler "https://github.com/minvws/nl-rdo-max/blob/main/app/services/loginhandler/mock_saml_authentication_handler.py"
    click Rate_Limiter "https://github.com/minvws/nl-rdo-max/blob/main/app/misc/rate_limiter.py"

    %% Click Events for External Providers
    click OIDC_Provider "https://github.com/minvws/nl-rdo-max/blob/main/app/providers/oidc_provider.py"
    click SAML_Provider "https://github.com/minvws/nl-rdo-max/blob/main/app/providers/saml_provider.py"
    click DigiD_Provider "https://github.com/minvws/nl-rdo-max/blob/main/app/providers/digid_mock_provider.py"
    click Pyop_Provider "https://github.com/minvws/nl-rdo-max/blob/main/app/providers/pyop_provider.py"

    %% Click Event for Storage & Caching
    click Redis_Cache "https://github.com/minvws/nl-rdo-max/tree/main/app/storage/redis"

    %% Styling Classes
    classDef client fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef router fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef di fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef models fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef service fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef encryption fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef ratelimiter fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef provider fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef storage fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
```
