# dbis-legal-llms/auth-service architecture

> Architecture diagram of the GitHub repository dbis-legal-llms/auth-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dbis-legal-llms/auth-service
- Repository: https://github.com/dbis-legal-llms/auth-service

## Overview

auth-service is a standalone identity and role-bookkeeping API. Its main workflow registers users, authenticates them, resolves roles across registered applications, and returns RS256 access plus rotating refresh tokens; consuming apps verify access tokens through the published JWKS. Separate account-management and application-registry endpoints support role assignment, superuser administration, and per-user OpenRouter keys. The graph follows the sampled route/service calls; broader endpoint capabilities are retained from the README, while unsampled implementation links are omitted rather than inferred.

Main entry points: [`app/services/user_service.py`](https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/user_service.py) (User service), [`app/main.py`](https://github.com/dbis-legal-llms/auth-service/blob/main/app/main.py) (FastAPI application), [`app/api/routes/auth_routes.py`](https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/auth_routes.py) (Auth endpoints), [`app/api/routes/user_routes.py`](https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/user_routes.py) (User endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and sessions"]
  node_main["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth endpoints<br/>[auth_routes.py]"]
  node_user_routes["User endpoints<br/>[user_routes.py]"]
  node_application_routes["Application endpoint"]
  node_jwks_routes["JWKS endpoint<br/>[jwks_routes.py]"]
end

subgraph group_identity["Identity and roles"]
  node_user_service["User service<br/>[user_service.py]"]
  node_user_models["User models<br/>[user_models.py]"]
  node_role_resolution["Role resolution<br/>[role_resolution.py]"]
  node_application_service["Application registry"]
  node_application_models["Application models"]
end

subgraph group_security["Token security"]
  node_refresh_service["Refresh sessions"]
  node_jwt["JWT and JWKS<br/>[jwt.py]"]
  node_keys["RSA key management<br/>[keys.py]"]
  node_deps["Auth dependencies<br/>[deps.py]"]
  node_security_helpers["Password and secrets<br/>[security.py]"]
end

subgraph group_persistence["Persistence and registry"]
  node_mongo[("MongoDB<br/>[mongo.py]")]
  node_config["Runtime settings<br/>[config.py]"]
  node_username_data["Username word lists<br/>[func.py]"]
end

node_client(("API client"))
node_consumer["Consuming apps"]

node_client -->|"calls API"| node_main
node_main -->|"mounts routes"| node_auth_routes
node_main -->|"mounts routes"| node_user_routes
node_main -->|"mounts routes"| node_application_routes
node_main -->|"mounts routes"| node_jwks_routes
node_main -->|"gets database"| node_mongo
node_main -->|"ensures indexes"| node_refresh_service
node_auth_routes -->|"registers and verifies"| node_user_service
node_auth_routes -->|"loads registered apps"| node_application_service
node_auth_routes -->|"resolves token roles"| node_role_resolution
node_auth_routes -->|"starts and rotates"| node_refresh_service
node_auth_routes -->|"mints access token"| node_jwt
node_auth_routes -->|"accepts user input"| node_user_models
node_user_routes -->|"manages accounts"| node_user_service
node_user_routes -->|"loads app roles"| node_application_service
node_user_routes -->|"checks app admin"| node_role_resolution
node_user_routes -->|"revokes sessions"| node_refresh_service
node_user_routes -->|"reauthenticates password"| node_security_helpers
node_application_routes -->|"lists applications"| node_application_service
node_jwks_routes -->|"serializes public keys"| node_jwt
node_consumer -->|"fetches signing keys"| node_jwks_routes
node_consumer -.->|"verifies access tokens"| node_jwt
node_jwt -->|"gets signing keys"| node_keys
node_deps -->|"verifies bearer token"| node_jwt
node_deps -->|"loads current user"| node_user_service
node_deps -->|"gets database"| node_mongo
node_user_service -->|"reads and writes users"| node_mongo
node_user_service -->|"hashes and verifies passwords"| node_security_helpers
node_user_service -->|"uses word lists"| node_username_data
node_user_service -->|"creates user records"| node_user_models
node_user_service -->|"uses app records"| node_application_models
node_user_service -->|"encrypts API keys"| node_security_helpers
node_application_service -->|"reads and writes registry"| node_mongo
node_application_service -->|"validates registry data"| node_application_models
node_refresh_service -->|"stores token hashes"| node_mongo
node_refresh_service -->|"reads token lifetime"| node_config
node_keys -->|"reads key location"| node_config
node_mongo -->|"reads connection settings"| node_config

click node_main "https://github.com/dbis-legal-llms/auth-service/blob/main/app/main.py"
click node_auth_routes "https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/auth_routes.py"
click node_user_routes "https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/user_routes.py"
click node_application_routes "https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/application_routes.py"
click node_jwks_routes "https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/jwks_routes.py"
click node_user_service "https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/user_service.py"
click node_user_models "https://github.com/dbis-legal-llms/auth-service/blob/main/app/models/user_models.py"
click node_role_resolution "https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/role_resolution.py"
click node_application_service "https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/application_service.py"
click node_application_models "https://github.com/dbis-legal-llms/auth-service/blob/main/app/models/application_models.py"
click node_refresh_service "https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/refresh_token_service.py"
click node_jwt "https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/jwt.py"
click node_keys "https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/keys.py"
click node_deps "https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/deps.py"
click node_security_helpers "https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/security.py"
click node_mongo "https://github.com/dbis-legal-llms/auth-service/blob/main/app/db/mongo.py"
click node_config "https://github.com/dbis-legal-llms/auth-service/blob/main/app/config.py"
click node_username_data "https://github.com/dbis-legal-llms/auth-service/blob/main/app/data/func.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_auth_routes,node_user_routes,node_application_routes,node_jwks_routes,node_client toneBlue
class node_user_service,node_user_models,node_role_resolution,node_application_service,node_application_models toneAmber
class node_refresh_service,node_jwt,node_keys,node_deps,node_security_helpers toneMint
class node_mongo,node_config,node_username_data toneRose
class node_consumer toneIndigo
```

## Components

### API and sessions

- [FastAPI application](https://github.com/dbis-legal-llms/auth-service/blob/main/app/main.py): `app/main.py`
- [Auth endpoints](https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/auth_routes.py): `app/api/routes/auth_routes.py`
- [User endpoints](https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/user_routes.py): `app/api/routes/user_routes.py`
- [Application endpoint](https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/application_routes.py): `app/api/routes/application_routes.py`
- [JWKS endpoint](https://github.com/dbis-legal-llms/auth-service/blob/main/app/api/routes/jwks_routes.py): `app/api/routes/jwks_routes.py`

### Identity and roles

- [User service](https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/user_service.py): `app/services/user_service.py`
- [User models](https://github.com/dbis-legal-llms/auth-service/blob/main/app/models/user_models.py): `app/models/user_models.py`
- [Role resolution](https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/role_resolution.py): `app/services/role_resolution.py`
- [Application registry](https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/application_service.py): `app/services/application_service.py`
- [Application models](https://github.com/dbis-legal-llms/auth-service/blob/main/app/models/application_models.py): `app/models/application_models.py`

### Token security

- [Refresh sessions](https://github.com/dbis-legal-llms/auth-service/blob/main/app/services/refresh_token_service.py): `app/services/refresh_token_service.py`
- [JWT and JWKS](https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/jwt.py): `app/core/jwt.py`
- [RSA key management](https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/keys.py): `app/core/keys.py`
- [Auth dependencies](https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/deps.py): `app/core/deps.py`
- [Password and secrets](https://github.com/dbis-legal-llms/auth-service/blob/main/app/core/security.py): `app/core/security.py`

### Persistence and registry

- [MongoDB](https://github.com/dbis-legal-llms/auth-service/blob/main/app/db/mongo.py): `app/db/mongo.py`
- [Runtime settings](https://github.com/dbis-legal-llms/auth-service/blob/main/app/config.py): `app/config.py`
- [Username word lists](https://github.com/dbis-legal-llms/auth-service/blob/main/app/data/func.py): `app/data/func.py`

### Other components

- **API client**
- **Consuming apps**

## Connections

- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Auth endpoints: mounts routes (evidence: `app/main.py`)
- FastAPI application → User endpoints: mounts routes (evidence: `app/main.py`)
- FastAPI application → Application endpoint: mounts routes (evidence: `app/main.py`)
- FastAPI application → JWKS endpoint: mounts routes (evidence: `app/main.py`)
- FastAPI application → MongoDB: gets database (evidence: `app/main.py`)
- FastAPI application → Refresh sessions: ensures indexes (evidence: `app/main.py`)
- Auth endpoints → User service: registers and verifies (evidence: `app/api/routes/auth_routes.py`)
- Auth endpoints → Application registry: loads registered apps (evidence: `app/api/routes/auth_routes.py`)
- Auth endpoints → Role resolution: resolves token roles (evidence: `app/api/routes/auth_routes.py`)
- Auth endpoints → Refresh sessions: starts and rotates (evidence: `app/api/routes/auth_routes.py`)
- Auth endpoints → JWT and JWKS: mints access token (evidence: `app/api/routes/auth_routes.py`)
- Auth endpoints → User models: accepts user input (evidence: `app/api/routes/auth_routes.py`)
- User endpoints → User service: manages accounts (evidence: `app/api/routes/user_routes.py`)
- User endpoints → Application registry: loads app roles (evidence: `app/api/routes/user_routes.py`)
- User endpoints → Role resolution: checks app admin (evidence: `app/api/routes/user_routes.py`)
- User endpoints → Refresh sessions: revokes sessions (evidence: `app/api/routes/user_routes.py`)
- User endpoints → Password and secrets: reauthenticates password (evidence: `app/api/routes/user_routes.py`)
- Application endpoint → Application registry: lists applications (evidence: `app/api/routes/application_routes.py`)
- JWKS endpoint → JWT and JWKS: serializes public keys (evidence: `app/api/routes/jwks_routes.py`)
- Consuming apps → JWKS endpoint: fetches signing keys (evidence: `README.md`)
- Consuming apps → JWT and JWKS: verifies access tokens (evidence: `README.md`)
- JWT and JWKS → RSA key management: gets signing keys (evidence: `app/core/jwt.py`)
- Auth dependencies → JWT and JWKS: verifies bearer token (evidence: `app/core/deps.py`)
- Auth dependencies → User service: loads current user (evidence: `app/core/deps.py`)
- Auth dependencies → MongoDB: gets database (evidence: `app/core/deps.py`)
- User service → MongoDB: reads and writes users (evidence: `app/services/user_service.py`)
- User service → Password and secrets: hashes and verifies passwords (evidence: `app/services/user_service.py`)
- User service → Username word lists: uses word lists (evidence: `app/services/user_service.py`)
- User service → User models: creates user records (evidence: `app/services/user_service.py`)
- User service → Application models: uses app records (evidence: `app/services/user_service.py`)
- User service → Password and secrets: encrypts API keys (evidence: `app/services/user_service.py`)
- Application registry → MongoDB: reads and writes registry (evidence: `app/services/application_service.py`)
- Application registry → Application models: validates registry data (evidence: `app/services/application_service.py`)
- Refresh sessions → MongoDB: stores token hashes (evidence: `app/services/refresh_token_service.py`)
- Refresh sessions → Runtime settings: reads token lifetime (evidence: `app/services/refresh_token_service.py`)
- RSA key management → Runtime settings: reads key location (evidence: `app/core/keys.py`)
- MongoDB → Runtime settings: reads connection settings (evidence: `app/db/mongo.py`)
