# pcnerd9/fastapi_boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/pcnerd9/fastapi_boilerplate
- Repository: https://github.com/pcnerd9/fastapi_boilerplate

## Overview

This is a FastAPI authentication service offering email OTP registration/login, cookie-based refreshable sessions, and Google OAuth/OIDC account creation and linking. Users enter through the API routes, which delegate authentication to domain services; successful flows create sessions and return access tokens while setting refresh-token cookies. The services use repositories backed by PostgreSQL, Redis for supporting authentication state, and email providers for OTP delivery. Google OAuth exchanges authorization codes and validates identity tokens. The README is empty, so capability details come from route documentation and indexed source references; several internal links remain unshown.

Main entry points: [`src/service/auth/google_auth.py`](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/google_auth.py) (Google auth), [`src/service/auth/otp_auth.py`](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/otp_auth.py) (OTP auth), [`src/api/dependencies.py`](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/dependencies.py) (Auth dependencies), [`main.py`](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/main.py) (App startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_main["App startup<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_oauth_routes["OAuth routes<br/>[oauth.py]"]
  node_dependencies["Auth dependencies<br/>[dependencies.py]"]
end

subgraph group_auth["Authentication"]
  node_otp_service["OTP auth<br/>[otp_auth.py]"]
  node_google_service["Google auth<br/>[google_auth.py]"]
  node_session_service["Session limits<br/>[session_service.py]"]
  node_tokens["Token utilities<br/>[token_manager.py]"]
  node_oidc["OIDC validation<br/>[oidc_validator.py]"]
  node_oauth_state["OAuth state<br/>[oauth_state.py]"]
end

subgraph group_data["Persistence"]
  node_otp_repo["OTP repository<br/>[otp_repository.py]"]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_refresh_repo["Session repository"]
  node_oauth_repo["Provider repository"]
  node_user_model["User model<br/>[user.py]"]
end

subgraph group_infra["Runtime infrastructure"]
  node_postgres[("PostgreSQL<br/>[postgres_db.py]")]
  node_redis[("Redis<br/>[redis.py]")]
  node_email_service["Email delivery<br/>[email_service.py]"]
  node_email_provider["Email providers"]
  node_config["Settings<br/>[config.py]"]
end

node_user(("Client"))
node_google["Google OIDC"]

node_user -->|"sends requests"| node_main
node_main -->|"registers routes"| node_auth_routes
node_main -->|"registers routes"| node_oauth_routes
node_auth_routes -->|"delegates OTP"| node_otp_service
node_oauth_routes -->|"delegates OAuth"| node_google_service
node_auth_routes -->|"requires identity"| node_dependencies
node_oauth_routes -->|"requires identity"| node_dependencies
node_dependencies -->|"decodes tokens"| node_tokens
node_dependencies -->|"checks revocation"| node_redis
node_dependencies -->|"loads user"| node_user_repo
node_otp_service -->|"manages OTPs"| node_otp_repo
node_otp_service -->|"manages users"| node_user_repo
node_otp_service -->|"manages sessions"| node_refresh_repo
node_otp_service -->|"sends OTP"| node_email_service
node_otp_service -->|"enforces limits"| node_session_service
node_otp_service -->|"issues tokens"| node_tokens
node_google_service -->|"stores state"| node_oauth_state
node_google_service -->|"exchanges code"| node_google
node_google_service -->|"validates identity"| node_oidc
node_google_service -->|"resolves account"| node_user_repo
node_google_service -->|"links provider"| node_oauth_repo
node_google_service -->|"creates session"| node_refresh_repo
node_google_service -->|"enforces limits"| node_session_service
node_session_service -->|"deletes old sessions"| node_refresh_repo
node_email_service -->|"uses provider"| node_email_provider
node_user_repo -->|"queries model"| node_user_model
node_otp_repo -.->|"persists OTPs"| node_postgres
node_refresh_repo -->|"persists sessions"| node_postgres
node_oauth_repo -.->|"persists links"| node_postgres
node_user_model -->|"maps tables"| node_postgres
node_main -->|"loads settings"| node_config
node_google_service -.->|"stores OAuth state"| node_redis

click node_main "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/main.py"
click node_auth_routes "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/routes/auth.py"
click node_oauth_routes "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/routes/oauth.py"
click node_dependencies "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/dependencies.py"
click node_otp_service "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/otp_auth.py"
click node_google_service "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/google_auth.py"
click node_session_service "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/session_service.py"
click node_tokens "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/security/token_manager.py"
click node_oidc "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/security/oidc_validator.py"
click node_oauth_state "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/security/oauth_state.py"
click node_otp_repo "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/otp_repository.py"
click node_user_repo "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/user_repository.py"
click node_refresh_repo "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/refresh_token_repository.py"
click node_oauth_repo "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/oauth_provider_repository.py"
click node_user_model "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/models/user.py"
click node_postgres "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/infrastructure/database/postgres_db.py"
click node_redis "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/infrastructure/database/redis.py"
click node_email_service "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/email_service.py"
click node_email_provider "https://github.com/pcnerd9/fastapi_boilerplate/tree/main/src/infrastructure/email_provider"
click node_config "https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/config.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_oauth_routes,node_dependencies,node_user toneBlue
class node_otp_service,node_google_service,node_session_service,node_tokens,node_oidc,node_oauth_state toneAmber
class node_otp_repo,node_user_repo,node_refresh_repo,node_oauth_repo,node_user_model toneMint
class node_postgres,node_redis,node_email_service,node_email_provider,node_config toneRose
class node_google toneIndigo
```

## Components

### HTTP API

- [App startup](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/main.py): `main.py`
- [Auth routes](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/routes/auth.py): `src/api/routes/auth.py`
- [OAuth routes](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/routes/oauth.py): `src/api/routes/oauth.py`
- [Auth dependencies](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/api/dependencies.py): `src/api/dependencies.py`

### Authentication

- [OTP auth](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/otp_auth.py): `src/service/auth/otp_auth.py`
- [Google auth](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/google_auth.py): `src/service/auth/google_auth.py`
- [Session limits](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/auth/session_service.py): `src/service/auth/session_service.py`
- [Token utilities](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/security/token_manager.py): `src/core/security/token_manager.py`
- [OIDC validation](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/security/oidc_validator.py): `src/core/security/oidc_validator.py`
- [OAuth state](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/security/oauth_state.py): `src/core/security/oauth_state.py`

### Persistence

- [OTP repository](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/otp_repository.py): `src/repository/otp_repository.py`
- [User repository](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/user_repository.py): `src/repository/user_repository.py`
- [Session repository](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/refresh_token_repository.py): `src/repository/refresh_token_repository.py`
- [Provider repository](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/repository/oauth_provider_repository.py): `src/repository/oauth_provider_repository.py`
- [User model](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/models/user.py): `src/models/user.py`

### Runtime infrastructure

- [PostgreSQL](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/infrastructure/database/postgres_db.py): `src/infrastructure/database/postgres_db.py`
- [Redis](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/infrastructure/database/redis.py): `src/infrastructure/database/redis.py`
- [Email delivery](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/service/email_service.py): `src/service/email_service.py`
- [Email providers](https://github.com/pcnerd9/fastapi_boilerplate/tree/main/src/infrastructure/email_provider): `src/infrastructure/email_provider`
- [Settings](https://github.com/pcnerd9/fastapi_boilerplate/blob/main/src/core/config.py): `src/core/config.py`

### Other components

- **Client**
- **Google OIDC**

## Connections

- Client → App startup: sends requests (evidence: `main.py`)
- App startup → Auth routes: registers routes
- App startup → OAuth routes: registers routes
- Auth routes → OTP auth: delegates OTP (evidence: `src/api/routes/auth.py`)
- OAuth routes → Google auth: delegates OAuth (evidence: `src/api/routes/oauth.py`)
- Auth routes → Auth dependencies: requires identity (evidence: `src/api/routes/auth.py`)
- OAuth routes → Auth dependencies: requires identity (evidence: `src/api/routes/oauth.py`)
- Auth dependencies → Token utilities: decodes tokens (evidence: `src/api/dependencies.py`)
- Auth dependencies → Redis: checks revocation (evidence: `src/api/dependencies.py`)
- Auth dependencies → User repository: loads user (evidence: `src/api/dependencies.py`)
- OTP auth → OTP repository: manages OTPs (evidence: `src/service/auth/otp_auth.py`)
- OTP auth → User repository: manages users (evidence: `src/service/auth/otp_auth.py`)
- OTP auth → Session repository: manages sessions (evidence: `src/service/auth/otp_auth.py`)
- OTP auth → Email delivery: sends OTP (evidence: `src/service/auth/otp_auth.py`)
- OTP auth → Session limits: enforces limits (evidence: `src/service/auth/otp_auth.py`)
- OTP auth → Token utilities: issues tokens (evidence: `src/service/auth/otp_auth.py`)
- Google auth → OAuth state: stores state (evidence: `src/service/auth/google_auth.py`)
- Google auth → Google OIDC: exchanges code (evidence: `src/service/auth/google_auth.py`)
- Google auth → OIDC validation: validates identity (evidence: `src/service/auth/google_auth.py`)
- Google auth → User repository: resolves account (evidence: `src/service/auth/google_auth.py`)
- Google auth → Provider repository: links provider (evidence: `src/service/auth/google_auth.py`)
- Google auth → Session repository: creates session (evidence: `src/service/auth/google_auth.py`)
- Google auth → Session limits: enforces limits (evidence: `src/service/auth/google_auth.py`)
- Session limits → Session repository: deletes old sessions (evidence: `src/service/auth/session_service.py`)
- Email delivery → Email providers: uses provider (evidence: `src/service/email_service.py`)
- User repository → User model: queries model (evidence: `src/repository/user_repository.py`)
- OTP repository → PostgreSQL: persists OTPs
- Session repository → PostgreSQL: persists sessions (evidence: `src/repository/refresh_token_repository.py`)
- Provider repository → PostgreSQL: persists links
- User model → PostgreSQL: maps tables (evidence: `src/models/user.py`)
- App startup → Settings: loads settings (evidence: `main.py`)
- Google auth → Redis: stores OAuth state
