# fastapi-users/fastapi-users architecture

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

- Interactive diagram: https://gitdiagram.com/fastapi-users/fastapi-users
- Repository: https://github.com/fastapi-users/fastapi-users

## Overview

##### Project type and purpose
- Type: Open-source Python library (plugin) for FastAPI.
- Purpose: Provide ready-to-use, customizable routes and logic for user registration, authentication (JWT, database, Redis), password reset, email verification, OAuth2 social login, and full OpenAPI schema support.

##### High-level file-structure analysis
- Top-level directories:
– fastapi_users/: core library code (authentication, router, db adapters, manager, schemas, models, OpenAPI).
– examples/: sample FastAPI apps demonstrating different database backends and OAuth flows.
– docs/: MkDocs-based documentation, configuration guides, and code snippets.
– tests/: unit tests covering all strategies, transports, managers, routers, and OpenAPI.
- Configuration/build: Hatch for environment and tasks, GitHub Actions workflows, mkdocs.yml, pyproject.toml.

##### Key insights from README
- Modular, extensible design with clear extension points:
– Pluggable authentication backends (strategies + transports).
– Swappable database adapters (SQLAlchemy async ORM, Beanie ODM).
– Ready-to-mount FastAPI routers for each user flow.
- Examples show how host apps call into the library.

##### Main components
A. Host FastAPI Application (external)
- Registers the FastAPI Users instance and mounts routers.
- Supplies: user model, database session, secret keys, email sender, OAuth client config.

B. fastapi_users Library (internal)
1. Router Layer
– auth.py, register.py, reset.py, verify.py, users.py, oauth.py
– Exposes HTTP endpoints: POST /register, POST /login, GET /verify, etc.
2. Authentication Layer
a. Transports (fastapi_users/authentication/transport):
- bearer.py (Authorization header)
- cookie.py
b. Strategies (fastapi_users/authentication/strategy):
- jwt.py
- db/strategy.py (database sessions)
- redis.py
c. Authenticator (authenticator.py) orchestrates strategy + transport.
3. Manager (manager.py)
– Business logic: hashing passwords, generating tokens, sending emails, verifying codes.
4. Database Adapters (fastapi_users/db)
– Base adapter, SQLAlchemy, Beanie implementations.
– Models (adapter.py), CRUD operations.
5. Schemas & Models
– Pydantic schemas (UserCreate, UserRead, UserUpdate) and ORM models.
6. OpenAPI Integration (openapi.py)
– Merges multiple auth backends into FastAPI’s security schemes.

C. External Services
- Relational Database (PostgreSQL/MySQL via SQLAlchemy)
- MongoDB (via Beanie)
- Redis (optional session/token store)
- Email service (SMTP or third-party)
- OAuth2 Providers (Google, Facebook, etc.)

##### Relationships & data flows
1. Client → HTTP Request → FastAPI App
2. FastAPI App → Mounted Router → Endpoint handler
3. Endpoint handler → Authenticator
– Transport extracts credentials from header/cookie.
– Strategy verifies credentials (JWT decode or DB lookup or Redis).
4. On registration/reset/verify: Handler calls Manager → generates token/reset link → sends via Email service.
5. Manager/Authenticator → Database Adapter → External Database
6. Authenticator → issues or validates JWT tokens or session IDs → returns to client via transport.

##### Architectural patterns & principles
- Modular layering (Router → Authenticator → Manager → DB).
- Dependency injection (FastAPI dependencies for current_user, DB session).
- Strategy pattern for authentication and transport.
- Adapter pattern for multiple databases.
- OpenAPI auto-generation via schema introspection.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Application"
        HostApp["FastAPI Host App"]:::host
    end

    subgraph "fastapi_users Library"
        subgraph "Router Layer"
            RAuth["auth.py"]:::internal
            RRegister["register.py"]:::internal
            RReset["reset.py"]:::internal
            RVerify["verify.py"]:::internal
            RUsers["users.py"]:::internal
            ROAuth["oauth.py"]:::internal
        end

        subgraph "Authentication Layer"
            Authenticator["Authenticator"]:::internal
            subgraph Transports
                TBearer["bearer.py"]:::internal
                TCookie["cookie.py"]:::internal
            end
            subgraph Strategies
                SJWT["jwt.py"]:::internal
                SRedis["redis.py"]:::internal
                SDB["db/strategy.py"]:::internal
            end
        end

        Manager["manager.py"]:::internal

        subgraph "Database Adapters"
            DBBase["base.py"]:::internal
        end

        subgraph "Schemas & Models"
            Schemas["schemas.py"]:::internal
            Models["models.py"]:::internal
        end

        OpenAPI["openapi.py"]:::internal

        subgraph "Utilities"
            Password["password.py"]:::internal
            JWTUtils["jwt.py"]:::internal
        end

        Core["fastapi_users.py"]:::internal
    end

    subgraph "External Services"
        RelDB[(Relational DB)]:::external
        MongoDB[(MongoDB)]:::external
        Redis[(Redis)]:::external
        Email[(Email Service)]:::external
        OAuthProv[(OAuth2 Providers)]:::external
    end

    HostApp -->|Mount routers| RAuth
    HostApp --> RRegister
    HostApp --> RReset
    HostApp --> RVerify
    HostApp --> RUsers
    HostApp --> ROAuth
    HostApp -->|Provide config| Core

    RAuth -->|handle auth| Authenticator
    RRegister -->|"POST /register"| Manager
    RReset -->|"POST /reset"| Manager
    RVerify -->|"GET /verify"| Manager
    RUsers -->|"CRUD ops"| Manager
    ROAuth -->|"OAuth flow"| Authenticator

    Authenticator --> TBearer
    Authenticator --> TCookie
    Authenticator --> SJWT
    Authenticator --> SRedis
    Authenticator --> SDB
    Authenticator -->|delegate| Manager

    Manager --> DBBase
    DBBase --> RelDB
    DBBase --> MongoDB
    Manager --> Email

    Authenticator --> Redis
    Authenticator --> JWTUtils

    Core --> OpenAPI
    Core --> Schemas
    Core --> Models
    Core --> Manager

    OAuthProv --> ROAuth

    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef host fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFFF99,stroke:#000,stroke-width:1px

    click RAuth "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/router/auth.py"
    click RRegister "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/router/register.py"
    click RReset "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/router/reset.py"
    click RVerify "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/router/verify.py"
    click RUsers "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/router/users.py"
    click ROAuth "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/router/oauth.py"

    click Authenticator "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/authentication/authenticator.py"
    click TBearer "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/authentication/transport/bearer.py"
    click TCookie "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/authentication/transport/cookie.py"
    click SJWT "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/authentication/strategy/jwt.py"
    click SRedis "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/authentication/strategy/redis.py"
    click SDB "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/authentication/strategy/db/strategy.py"

    click Manager "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/manager.py"
    click DBBase "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/db/base.py"
    click Schemas "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/schemas.py"
    click Models "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/models.py"
    click Core "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/fastapi_users.py"
    click OpenAPI "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/openapi.py"
    click Password "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/password.py"
    click JWTUtils "https://github.com/fastapi-users/fastapi-users/blob/master/fastapi_users/jwt.py"
```
