# madhvesh77/sso-spike-backend architecture

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

- Interactive diagram: https://gitdiagram.com/madhvesh77/sso-spike-backend
- Repository: https://github.com/madhvesh77/sso-spike-backend

## Overview

##### Project type and purpose
- This is a small, self-contained FastAPI microservice whose sole purpose is to expose three HTTP endpoints and protect two of them with Microsoft Entra ID (Azure AD) JWT authentication.
- It validates incoming Bearer tokens by fetching the JSON Web Key Set (JWKS) from Azure AD, caches the keys, verifies signature, expiration, issuer, audience and enforces role-based access.

##### File structure
- Top level:
- auth.py      → encapsulates all JWT validation logic and JWKS fetching/caching
- main.py      → FastAPI app, defines routes, imports auth logic as dependency/middleware
- requirements.txt, .env.example → environment and dependency setup
- README.md    → documentation
- No database, no message queues or other services—pure HTTP API and external Azure AD JWKS.

##### Readme insights
- The README describes endpoints, required environment variables (TENANT_ID, API_AUDIENCE), and the security features (RSA256 signature check, TTL-cached JWKS, RBAC).
- It clearly calls out three endpoints: /health (public), /api/profile (any valid JWT), /api/admin-only (requires “approver” role).

##### Main components
a. Client (could be web app, mobile app, curl, Postman)
b. FastAPI microservice
– API Gateway layer (uvicorn)
– Routing layer (/health, /api/profile, /api/admin-only)
– Authentication middleware (auth.py)
– JWKS cache component (in-memory TTL cache via cachetools)
c. Microsoft Entra ID (Azure AD) JWKS endpoint (external service)

##### Relationships and data flow
1. Client sends HTTP request to FastAPI.
2. Routing layer invokes authentication middleware for protected routes.
3. Auth module checks in-memory cache for signing keys.
– Cache hit → verify JWT signature, claims, roles
– Cache miss → HTTP GET to Azure AD JWKS endpoint → populate cache → verify
4. On success, control returns to route handler (profile or admin logic), returns JSON.
5. /health bypasses auth and returns {"ok": true}.

##### Architectural patterns and principles
- Separation of concerns: routing (main.py) vs. security logic (auth.py).
- Caching layer to reduce external calls (cachetools TTL).
- Dependency injection via FastAPI’s Depends for middleware.
- Stateless service: no local session store, JWT holds all identity data.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef inproc fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef client fill:#F7DC6F,stroke:#333,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef doc fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef arrow stroke:#333,stroke-width:1px,stroke-dasharray: 0

    Client["Client\n(web/mobile/CLI)"]:::client
    Client -->|"HTTP Request"| Routing

    subgraph "FastAPI Service\n(uvicorn)" 
        direction TB
        Routing["Routing Layer\n(/health, /api/profile, /api/admin-only)"]:::inproc
        Auth["Auth Middleware\n(JWT validation)\n(auth.py)"]:::inproc
        Cache[("JWKS Cache\n(cachetools)\nTTL=1h")]:::inproc
        Routing -->|"protected routes"| Auth
        Routing -->|"/health\n(bypass auth)"| Health["/health\n(public)"]:::inproc
        Auth -->|"check cache"| Cache
        Cache -->|"JWKS fetch on miss"| Azure
        Azure -->|"JWKS response"| Cache
        Auth -->|"validated → handler"| Handler["Route Handler\n(return JSON)"]:::inproc
        Handler -->|"HTTP Response"| Response
    end

    Response -->|"return"| Client

    subgraph "Configuration" 
        direction TB
        Env["Environment Config\nTENANT_ID, API_AUDIENCE\n(.env.example)"]:::config
    end
    Env --> Auth

    subgraph "Documentation & Dependencies"
        direction TB
        Docs["README.md"]:::doc
        Req["requirements.txt"]:::doc
    end

    Azure["Azure AD JWKS Endpoint"]:::external

    click Routing "https://github.com/madhvesh77/sso-spike-backend/blob/main/main.py"
    click Auth "https://github.com/madhvesh77/sso-spike-backend/blob/main/auth.py"
    click Cache "https://github.com/madhvesh77/sso-spike-backend/blob/main/auth.py"
    click Env "https://github.com/madhvesh77/sso-spike-backend/blob/main/.env.example"
    click Docs "https://github.com/madhvesh77/sso-spike-backend/blob/main/README.md"
    click Req "https://github.com/madhvesh77/sso-spike-backend/blob/main/requirements.txt"
```
