# branavanj/api-auth architecture

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

- Interactive diagram: https://gitdiagram.com/branavanj/api-auth
- Repository: https://github.com/branavanj/api-auth

## Overview

Auth API is a FastAPI service for registration, verified-email login, mandatory MFA, session management, and account security. The main flow is registration and email verification, password login, MFA challenge verification, then access/refresh tokens; authenticated users can manage profiles and TOTP/backup codes. PostgreSQL holds user and backup-code records, while Redis holds challenges, OTP state, sessions, replay markers, and rate-limit counters. Major documented health and structured logging capabilities are included. Connections are based on excerpts, the SOURCE INDEX, and README; health and mailer internals were not fully sampled.

Main entry points: [`app/routers/auth.py`](https://github.com/branavanj/api-auth/blob/main/app/routers/auth.py) (Auth routes), [`app/main.py`](https://github.com/branavanj/api-auth/blob/main/app/main.py) (FastAPI app), [`app/routers/twofa.py`](https://github.com/branavanj/api-auth/blob/main/app/routers/twofa.py) (2FA routes), [`app/models.py`](https://github.com/branavanj/api-auth/blob/main/app/models.py) (User records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and accounts"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Auth routes<br/>[auth.py]"]
  node_profile["Profile routes<br/>[me.py]"]
  node_twofa["2FA routes<br/>[twofa.py]"]
  node_deps["Auth dependencies<br/>[deps.py]"]
end

subgraph group_identity["Identity and MFA"]
  node_security["Password and tokens<br/>[security.py]"]
  node_sessions["Session lifecycle<br/>[sessions.py]"]
  node_totp["TOTP verification<br/>[totp.py]"]
  node_backup["Backup codes<br/>[backup_codes.py]"]
end

subgraph group_state["State and persistence"]
  node_stores["Challenge and OTP state<br/>[stores.py]"]
  node_limits["Rate limiting<br/>[rate_limit.py]"]
  node_models["User records<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[02-schema.sql]")]
  node_redis[("Redis<br/>[redis_client.py]")]
end

subgraph group_ops["Operations"]
  node_health["Health routes<br/>[health.py]"]
  node_mailer["Email delivery<br/>[mailer.py]"]
  node_logging["Request and audit logs<br/>[logging_config.py]"]
  node_settings["Configuration<br/>[config.py]"]
end

node_client(("API client"))
node_smtp["SMTP service"]

node_client -->|"sends requests"| node_app
node_app -->|"routes to"| node_auth
node_app -->|"routes to"| node_twofa
node_app -->|"routes to"| node_profile
node_app -->|"routes to"| node_health
node_app -->|"installs middleware"| node_logging
node_app -->|"creates schema"| node_database
node_auth -->|"reads and writes"| node_models
node_auth -->|"manages challenges"| node_stores
node_auth -->|"issues sessions"| node_sessions
node_auth -->|"verifies TOTP"| node_totp
node_auth -->|"consumes codes"| node_backup
node_auth -->|"checks passwords"| node_security
node_auth -->|"enforces limits"| node_limits
node_auth -->|"sends codes"| node_mailer
node_twofa -->|"updates MFA"| node_models
node_twofa -->|"sets and verifies"| node_totp
node_twofa -->|"replaces codes"| node_backup
node_twofa -->|"checks and encrypts"| node_security
node_twofa -->|"enforces limits"| node_limits
node_profile -->|"checks passwords"| node_security
node_profile -->|"updates account"| node_models
node_profile -->|"enforces limits"| node_limits
node_deps -->|"decodes access token"| node_security
node_deps -->|"loads user"| node_models
node_sessions -->|"creates tokens"| node_security
node_sessions -->|"checks user version"| node_models
node_auth -->|"persists account data"| node_database
node_backup -->|"stores code hashes"| node_models
node_stores -->|"hashes codes and tokens"| node_security
node_limits -->|"audits excesses"| node_logging
node_models -->|"maps records"| node_database
node_auth -->|"uses state store"| node_redis
node_sessions -->|"stores refresh state"| node_redis
node_mailer -.->|"delivers email"| node_smtp
node_health -->|"checks readiness"| node_database
node_health -->|"checks readiness"| node_redis
node_settings -->|"configures connection"| node_database
node_settings -->|"configures connection"| node_redis
node_settings -->|"configures SMTP"| node_mailer
node_auth -->|"emits audit events"| node_logging
node_twofa -->|"emits audit events"| node_logging
node_profile -->|"emits audit events"| node_logging

click node_app "https://github.com/branavanj/api-auth/blob/main/app/main.py"
click node_auth "https://github.com/branavanj/api-auth/blob/main/app/routers/auth.py"
click node_profile "https://github.com/branavanj/api-auth/blob/main/app/routers/me.py"
click node_twofa "https://github.com/branavanj/api-auth/blob/main/app/routers/twofa.py"
click node_health "https://github.com/branavanj/api-auth/blob/main/app/routers/health.py"
click node_deps "https://github.com/branavanj/api-auth/blob/main/app/deps.py"
click node_security "https://github.com/branavanj/api-auth/blob/main/app/security.py"
click node_sessions "https://github.com/branavanj/api-auth/blob/main/app/sessions.py"
click node_totp "https://github.com/branavanj/api-auth/blob/main/app/totp.py"
click node_backup "https://github.com/branavanj/api-auth/blob/main/app/backup_codes.py"
click node_stores "https://github.com/branavanj/api-auth/blob/main/app/stores.py"
click node_limits "https://github.com/branavanj/api-auth/blob/main/app/rate_limit.py"
click node_models "https://github.com/branavanj/api-auth/blob/main/app/models.py"
click node_database "https://github.com/branavanj/api-auth/blob/main/db/init/02-schema.sql"
click node_redis "https://github.com/branavanj/api-auth/blob/main/app/redis_client.py"
click node_mailer "https://github.com/branavanj/api-auth/blob/main/app/mailer.py"
click node_logging "https://github.com/branavanj/api-auth/blob/main/app/logging_config.py"
click node_settings "https://github.com/branavanj/api-auth/blob/main/app/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_app,node_auth,node_profile,node_twofa,node_deps,node_client toneBlue
class node_security,node_sessions,node_totp,node_backup toneAmber
class node_stores,node_limits,node_models,node_database,node_redis toneMint
class node_health,node_mailer,node_logging,node_settings toneRose
class node_smtp toneIndigo
```

## Components

### API and accounts

- [FastAPI app](https://github.com/branavanj/api-auth/blob/main/app/main.py): `app/main.py`
- [Auth routes](https://github.com/branavanj/api-auth/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Profile routes](https://github.com/branavanj/api-auth/blob/main/app/routers/me.py): `app/routers/me.py`
- [2FA routes](https://github.com/branavanj/api-auth/blob/main/app/routers/twofa.py): `app/routers/twofa.py`
- [Auth dependencies](https://github.com/branavanj/api-auth/blob/main/app/deps.py): `app/deps.py`

### Identity and MFA

- [Password and tokens](https://github.com/branavanj/api-auth/blob/main/app/security.py): `app/security.py`
- [Session lifecycle](https://github.com/branavanj/api-auth/blob/main/app/sessions.py): `app/sessions.py`
- [TOTP verification](https://github.com/branavanj/api-auth/blob/main/app/totp.py): `app/totp.py`
- [Backup codes](https://github.com/branavanj/api-auth/blob/main/app/backup_codes.py): `app/backup_codes.py`

### State and persistence

- [Challenge and OTP state](https://github.com/branavanj/api-auth/blob/main/app/stores.py): `app/stores.py`
- [Rate limiting](https://github.com/branavanj/api-auth/blob/main/app/rate_limit.py): `app/rate_limit.py`
- [User records](https://github.com/branavanj/api-auth/blob/main/app/models.py): `app/models.py`
- [PostgreSQL](https://github.com/branavanj/api-auth/blob/main/db/init/02-schema.sql): `db/init/02-schema.sql`
- [Redis](https://github.com/branavanj/api-auth/blob/main/app/redis_client.py): `app/redis_client.py`

### Operations

- [Health routes](https://github.com/branavanj/api-auth/blob/main/app/routers/health.py): `app/routers/health.py`
- [Email delivery](https://github.com/branavanj/api-auth/blob/main/app/mailer.py): `app/mailer.py`
- [Request and audit logs](https://github.com/branavanj/api-auth/blob/main/app/logging_config.py): `app/logging_config.py`
- [Configuration](https://github.com/branavanj/api-auth/blob/main/app/config.py): `app/config.py`

### Other components

- **API client**
- **SMTP service**

## Connections

- API client → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Auth routes: routes to (evidence: `app/main.py`)
- FastAPI app → 2FA routes: routes to (evidence: `app/main.py`)
- FastAPI app → Profile routes: routes to (evidence: `app/main.py`)
- FastAPI app → Health routes: routes to (evidence: `app/main.py`)
- FastAPI app → Request and audit logs: installs middleware (evidence: `app/main.py`)
- FastAPI app → PostgreSQL: creates schema (evidence: `app/main.py`)
- Auth routes → User records: reads and writes (evidence: `app/routers/auth.py`)
- Auth routes → Challenge and OTP state: manages challenges (evidence: `app/routers/auth.py`)
- Auth routes → Session lifecycle: issues sessions (evidence: `app/routers/auth.py`)
- Auth routes → TOTP verification: verifies TOTP (evidence: `app/routers/auth.py`)
- Auth routes → Backup codes: consumes codes (evidence: `app/routers/auth.py`)
- Auth routes → Password and tokens: checks passwords (evidence: `app/routers/auth.py`)
- Auth routes → Rate limiting: enforces limits (evidence: `app/routers/auth.py`)
- Auth routes → Email delivery: sends codes (evidence: `app/routers/auth.py`)
- 2FA routes → User records: updates MFA (evidence: `app/routers/twofa.py`)
- 2FA routes → TOTP verification: sets and verifies (evidence: `app/routers/twofa.py`)
- 2FA routes → Backup codes: replaces codes (evidence: `app/routers/twofa.py`)
- 2FA routes → Password and tokens: checks and encrypts (evidence: `app/routers/twofa.py`)
- 2FA routes → Rate limiting: enforces limits (evidence: `app/routers/twofa.py`)
- Profile routes → Password and tokens: checks passwords (evidence: `app/routers/me.py`)
- Profile routes → User records: updates account (evidence: `app/routers/me.py`)
- Profile routes → Rate limiting: enforces limits (evidence: `app/routers/me.py`)
- Auth dependencies → Password and tokens: decodes access token (evidence: `app/deps.py`)
- Auth dependencies → User records: loads user (evidence: `app/deps.py`)
- Session lifecycle → Password and tokens: creates tokens (evidence: `app/sessions.py`)
- Session lifecycle → User records: checks user version (evidence: `app/sessions.py`)
- Auth routes → PostgreSQL: persists account data (evidence: `README.md`)
- Backup codes → User records: stores code hashes (evidence: `app/backup_codes.py`)
- Challenge and OTP state → Password and tokens: hashes codes and tokens (evidence: `app/stores.py`)
- Rate limiting → Request and audit logs: audits excesses (evidence: `app/rate_limit.py`)
- User records → PostgreSQL: maps records (evidence: `app/models.py`)
- Auth routes → Redis: uses state store (evidence: `app/routers/auth.py`)
- Session lifecycle → Redis: stores refresh state (evidence: `app/sessions.py`)
- Email delivery → SMTP service: delivers email
- Health routes → PostgreSQL: checks readiness (evidence: `README.md`)
- Health routes → Redis: checks readiness (evidence: `README.md`)
- Configuration → PostgreSQL: configures connection
- Configuration → Redis: configures connection (evidence: `app/redis_client.py`)
- Configuration → Email delivery: configures SMTP (evidence: `app/mailer.py`)
- Auth routes → Request and audit logs: emits audit events (evidence: `app/routers/auth.py`)
- 2FA routes → Request and audit logs: emits audit events (evidence: `app/routers/twofa.py`)
- Profile routes → Request and audit logs: emits audit events (evidence: `app/routers/me.py`)
