# fief-dev/fief architecture

> Architecture diagram of the GitHub repository fief-dev/fief, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fief-dev/fief
- Repository: https://github.com/fief-dev/fief

## Overview

Fief is a users-and-authentication management service with separate authentication, administration UI, and administration API applications. The main user journey enters the authentication app for registration, sign-in, password recovery, or OAuth/token operations; account-management services support user changes and verification. Admins configure tenants, clients, access control, and customization through the dashboard or API. The tree documents further email, webhook, and background-task capabilities; their exact runtime wiring is not fully evidenced by the sampled source, so uncertain links are omitted.

Main entry points: [`fief/apps/auth/routers`](https://github.com/fief-dev/fief/tree/main/fief/apps/auth/routers) (Auth routes), [`fief/apps/auth/app.py`](https://github.com/fief-dev/fief/blob/main/fief/apps/auth/app.py) (Authentication app), [`fief/app.py`](https://github.com/fief-dev/fief/blob/main/fief/app.py) (ASGI application), [`fief/services/user_manager.py`](https://github.com/fief-dev/fief/blob/main/fief/services/user_manager.py) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entrypoints"]
  node_root_app["ASGI application<br/>[app.py]"]
  node_auth_app["Authentication app<br/>[app.py]"]
  node_dashboard["Admin dashboard<br/>[app.py]"]
  node_admin_api["Admin API<br/>[app.py]"]
end

subgraph group_identity["Identity workflows"]
  node_auth_routes["Auth routes"]
  node_registration["Registration flow"]
  node_authentication["Authentication flow"]
  node_oauth_tokens["OAuth and tokens<br/>[oauth.py]"]
  node_user_manager["User management<br/>[user_manager.py]"]
  node_crypto["Token and crypto"]
end

subgraph group_admin["Administration"]
  node_admin_routes["Dashboard routes"]
  node_api_routes["Admin API routes"]
end

subgraph group_platform["Shared platform"]
  node_webhook_service["Webhook delivery"]
  node_email_service["Email delivery"]
  node_background_tasks["Background tasks"]
  node_repositories["Data repositories"]
  node_database[("SQL database<br/>[engine.py]")]
end

node_end_user(("End user"))
node_admin_user(("Administrator"))
node_integrator(("Integrating app"))

node_end_user -->|"uses"| node_auth_app
node_integrator -->|"integrates"| node_auth_app
node_admin_user -->|"manages"| node_dashboard
node_integrator -->|"configures"| node_admin_api
node_root_app -->|"mounts"| node_auth_app
node_root_app -->|"mounts"| node_dashboard
node_root_app -->|"mounts"| node_admin_api
node_auth_app -->|"includes"| node_auth_routes
node_dashboard -->|"includes"| node_admin_routes
node_admin_api -->|"includes"| node_api_routes
node_auth_routes -->|"handles registration"| node_registration
node_auth_routes -->|"handles sign-in"| node_authentication
node_auth_routes -->|"handles OAuth"| node_oauth_tokens
node_auth_routes -->|"handles accounts"| node_user_manager
node_oauth_tokens -->|"uses"| node_crypto
node_user_manager -->|"reads and writes"| node_repositories
node_repositories -->|"persists"| node_database
node_user_manager -->|"schedules notifications"| node_background_tasks
node_background_tasks -->|"dispatches email"| node_email_service
node_background_tasks -->|"dispatches delivery"| node_webhook_service

click node_root_app "https://github.com/fief-dev/fief/blob/main/fief/app.py"
click node_auth_app "https://github.com/fief-dev/fief/blob/main/fief/apps/auth/app.py"
click node_dashboard "https://github.com/fief-dev/fief/blob/main/fief/apps/dashboard/app.py"
click node_admin_api "https://github.com/fief-dev/fief/blob/main/fief/apps/api/app.py"
click node_auth_routes "https://github.com/fief-dev/fief/tree/main/fief/apps/auth/routers"
click node_registration "https://github.com/fief-dev/fief/blob/main/fief/services/registration_flow.py"
click node_authentication "https://github.com/fief-dev/fief/blob/main/fief/services/authentication_flow.py"
click node_oauth_tokens "https://github.com/fief-dev/fief/blob/main/fief/apps/auth/routers/oauth.py"
click node_user_manager "https://github.com/fief-dev/fief/blob/main/fief/services/user_manager.py"
click node_crypto "https://github.com/fief-dev/fief/tree/main/fief/crypto"
click node_admin_routes "https://github.com/fief-dev/fief/tree/main/fief/apps/dashboard/routers"
click node_api_routes "https://github.com/fief-dev/fief/tree/main/fief/apps/api/routers"
click node_webhook_service "https://github.com/fief-dev/fief/tree/main/fief/services/webhooks"
click node_email_service "https://github.com/fief-dev/fief/tree/main/fief/services/email"
click node_background_tasks "https://github.com/fief-dev/fief/tree/main/fief/tasks"
click node_repositories "https://github.com/fief-dev/fief/tree/main/fief/repositories"
click node_database "https://github.com/fief-dev/fief/blob/main/fief/db/engine.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_root_app,node_auth_app,node_dashboard,node_admin_api,node_end_user toneBlue
class node_auth_routes,node_registration,node_authentication,node_oauth_tokens,node_user_manager,node_crypto toneAmber
class node_admin_routes,node_api_routes toneMint
class node_webhook_service,node_email_service,node_background_tasks,node_repositories,node_database toneRose
class node_admin_user,node_integrator toneIndigo
```

## Components

### Application entrypoints

- [ASGI application](https://github.com/fief-dev/fief/blob/main/fief/app.py): `fief/app.py`
- [Authentication app](https://github.com/fief-dev/fief/blob/main/fief/apps/auth/app.py): `fief/apps/auth/app.py`
- [Admin dashboard](https://github.com/fief-dev/fief/blob/main/fief/apps/dashboard/app.py): `fief/apps/dashboard/app.py`
- [Admin API](https://github.com/fief-dev/fief/blob/main/fief/apps/api/app.py): `fief/apps/api/app.py`

### Identity workflows

- [Auth routes](https://github.com/fief-dev/fief/tree/main/fief/apps/auth/routers): `fief/apps/auth/routers`
- [Registration flow](https://github.com/fief-dev/fief/blob/main/fief/services/registration_flow.py): `fief/services/registration_flow.py`
- [Authentication flow](https://github.com/fief-dev/fief/blob/main/fief/services/authentication_flow.py): `fief/services/authentication_flow.py`
- [OAuth and tokens](https://github.com/fief-dev/fief/blob/main/fief/apps/auth/routers/oauth.py): `fief/apps/auth/routers/oauth.py`
- [User management](https://github.com/fief-dev/fief/blob/main/fief/services/user_manager.py): `fief/services/user_manager.py`
- [Token and crypto](https://github.com/fief-dev/fief/tree/main/fief/crypto): `fief/crypto`

### Administration

- [Dashboard routes](https://github.com/fief-dev/fief/tree/main/fief/apps/dashboard/routers): `fief/apps/dashboard/routers`
- [Admin API routes](https://github.com/fief-dev/fief/tree/main/fief/apps/api/routers): `fief/apps/api/routers`

### Shared platform

- [Webhook delivery](https://github.com/fief-dev/fief/tree/main/fief/services/webhooks): `fief/services/webhooks`
- [Email delivery](https://github.com/fief-dev/fief/tree/main/fief/services/email): `fief/services/email`
- [Background tasks](https://github.com/fief-dev/fief/tree/main/fief/tasks): `fief/tasks`
- [Data repositories](https://github.com/fief-dev/fief/tree/main/fief/repositories): `fief/repositories`
- [SQL database](https://github.com/fief-dev/fief/blob/main/fief/db/engine.py): `fief/db/engine.py`

### Other components

- **End user**
- **Administrator**
- **Integrating app**

## Connections

- End user → Authentication app: uses
- Integrating app → Authentication app: integrates
- Administrator → Admin dashboard: manages
- Integrating app → Admin API: configures
- ASGI application → Authentication app: mounts
- ASGI application → Admin dashboard: mounts
- ASGI application → Admin API: mounts
- Authentication app → Auth routes: includes
- Admin dashboard → Dashboard routes: includes
- Admin API → Admin API routes: includes
- Auth routes → Registration flow: handles registration
- Auth routes → Authentication flow: handles sign-in
- Auth routes → OAuth and tokens: handles OAuth
- Auth routes → User management: handles accounts
- OAuth and tokens → Token and crypto: uses
- User management → Data repositories: reads and writes
- Data repositories → SQL database: persists
- User management → Background tasks: schedules notifications
- Background tasks → Email delivery: dispatches email
- Background tasks → Webhook delivery: dispatches delivery