# kdcllc/tokenflow architecture

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

- Interactive diagram: https://gitdiagram.com/kdcllc/tokenflow
- Repository: https://github.com/kdcllc/tokenflow

## Overview

##### Main Components

a) External Systems:
- Azure Active Directory (for device flow authentication)
- Azure Container App (hosting environment)
- Azure Blob Storage (state management)

b) Application Components:
- FastAPI Web Server
- Authentication Layer
- Token Management System
- API Endpoints Layer

**┌─ Client Layer ─────────────────────────┐**
- HTTP Clients                         │
- Azure CLI                            │
- ┬─┘
- ↓                     │
**┌─ Security Layer ────────────────────┼─┐**
- X-Auth-Token Validation           │ │
- Device Code Flow Authentication   │ │
- ┘
- ↓
**┌─ API Layer ──────────────────────────┐**
- Health Check Endpoint              │
- Device Code Endpoint              │
- Token Management Endpoints         │
- Subscription Management           │
- ┘
- ↓
**┌─ External Services ──────────────────┐**
- Azure AD                          │
- Azure Resource Management API     │
- Azure Blob Storage               │
- ┘

##### Key Relationships to Highlight

a) Authentication Flow:
- Client → Security Layer (X-Auth-Token validation)
- Security Layer → Azure AD (device code flow)
- Token Management → Azure AD (token refresh/validation)

b) Data Flow:
- API Layer → Azure Blob Storage (state persistence)
- API Layer → Azure Resource Management (resource operations)

##### Implementation Details

- FastAPI framework (main application server)
- Authentication middleware (src/auth_middleware.py)
- Token authenticator (src/token_authenticator.py)
- REST endpoints (shown in /rest directory)

##### Deployment Context

- Containerization boundary (Docker)
- Azure Container App hosting environment
- External dependency connections

This design should reflect the application's primary purpose of managing Azure authentication and resource access across multiple tenants, while showing the security measures in place to protect these operations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        CLI[Azure CLI]
        HTTP[HTTP Clients]
    end

    subgraph Security
        Auth["Authentication Layer"]:::security
        DevFlow["Device Code Flow"]:::security
        XAuth["X-Auth-Token Validation"]:::security
    end

    subgraph API
        FastAPI["FastAPI Web Server"]:::api
        Health["Health Check Endpoint"]:::api
        Device["Device Code Endpoint"]:::api
        Token["Token Management"]:::api
        Sub["Subscription Management"]:::api
    end

    subgraph External
        AD["Azure Active Directory"]:::azure
        ARM["Azure Resource Management"]:::azure
        Blob["Azure Blob Storage"]:::azure
        ACA["Azure Container App"]:::azure
    end

    %% Client to Security Layer
    CLI --> Auth
    HTTP --> Auth

    %% Security Layer Connections
    Auth --> DevFlow
    Auth --> XAuth
    DevFlow --> AD
    XAuth --> Token

    %% API Layer Connections
    FastAPI --> Health
    FastAPI --> Device
    FastAPI --> Token
    FastAPI --> Sub

    %% External Service Connections
    Token --> AD
    Token --> Blob
    Sub --> ARM
    FastAPI --> ACA

    %% Styles
    classDef security fill:#f96,stroke:#333
    classDef api fill:#9cf,stroke:#333
    classDef azure fill:#6f9,stroke:#333

    %% Click Events
    click Auth "https://github.com/kdcllc/tokenflow/blob/master/src/auth_middleware.py"
    click FastAPI "https://github.com/kdcllc/tokenflow/blob/master/src/api.py"
    click Token "https://github.com/kdcllc/tokenflow/blob/master/src/token_authenticator.py"
    click Health "https://github.com/kdcllc/tokenflow/blob/master/rest/healthz.http"
    click Device "https://github.com/kdcllc/tokenflow/blob/master/rest/device-code.http"
    click Sub "https://github.com/kdcllc/tokenflow/blob/master/rest/subscriptions.http"

    %% Legend
    subgraph Legend
        L1["Security Component"]:::security
        L2["API Component"]:::api
        L3["Azure Service"]:::azure
    end
```
