# ahmetfbalci/fastapi-jwt-auth architecture

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

- Interactive diagram: https://gitdiagram.com/ahmetfbalci/fastapi-jwt-auth
- Repository: https://github.com/ahmetfbalci/fastapi-jwt-auth

## Overview

This repository is a FastAPI authentication service. Clients register or log in with username/password, then receive JWT access and refresh tokens; refresh-token state supports renewal and logout revocation. A separate Google OAuth flow either signs in an existing linked account or issues a short-lived pending token so a new user can choose a username. The graph also includes the shared security, session, schema, and persistence layers. Connections reflect the sampled source and README; migrations and unsampled internals are not mapped.

Main entry points: [`app/routers/google_auth.py`](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/routers/google_auth.py) (Google auth), [`app/routers/auth.py`](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/routers/auth.py) (Password auth), [`app/database.py`](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/database.py) (Database session), [`app/main.py`](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API flows"]
  node_app["FastAPI app<br/>[main.py]"]
  node_password_flow["Password auth<br/>[auth.py]"]
  node_google_flow["Google auth<br/>[google_auth.py]"]
end

subgraph group_security["Identity security"]
  node_security_logic["Token and password security<br/>[security.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_session["Database session<br/>[database.py]"]
  node_user_model[("User records<br/>[user.py]")]
  node_account_model[("Provider accounts<br/>[AuthAccount.py]")]
  node_refresh_model[("Refresh-token records<br/>[refresh_token.py]")]
end

subgraph group_contracts["API contracts"]
  node_user_schema["User schemas<br/>[user.py]"]
  node_token_schema["Token schema<br/>[token.py]"]
end

node_client(("API client"))
node_google(("Google OAuth"))
node_postgres[("PostgreSQL")]

node_client -->|"sends requests"| node_app
node_app -->|"mounts router"| node_password_flow
node_app -->|"mounts router"| node_google_flow
node_app -->|"creates tables"| node_db_session
node_password_flow -->|"validates users"| node_user_schema
node_password_flow -->|"returns tokens"| node_token_schema
node_google_flow -->|"returns tokens"| node_token_schema
node_password_flow -->|"uses security"| node_security_logic
node_google_flow -->|"uses token functions"| node_security_logic
node_security_logic -->|"gets session"| node_db_session
node_security_logic -->|"loads current user"| node_user_model
node_password_flow -->|"gets session"| node_db_session
node_password_flow -->|"queries and writes"| node_user_model
node_password_flow -->|"stores and revokes"| node_refresh_model
node_google_flow -->|"gets session"| node_db_session
node_google_flow -->|"queries and creates"| node_user_model
node_google_flow -->|"looks up and links"| node_account_model
node_google_flow -->|"stores refresh tokens"| node_refresh_model
node_google -->|"authorizes callback"| node_google_flow
node_db_session -->|"connects to"| node_postgres
node_user_model -->|"uses declarative base"| node_db_session
node_account_model -->|"uses declarative base"| node_db_session
node_refresh_model -->|"uses declarative base"| node_db_session

click node_app "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/main.py"
click node_password_flow "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/routers/auth.py"
click node_google_flow "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/routers/google_auth.py"
click node_security_logic "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/core/security.py"
click node_user_schema "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/schemas/user.py"
click node_token_schema "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/schemas/token.py"
click node_db_session "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/database.py"
click node_user_model "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/models/user.py"
click node_account_model "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/models/AuthAccount.py"
click node_refresh_model "https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/models/refresh_token.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_password_flow,node_google_flow,node_client toneBlue
class node_security_logic,node_postgres toneAmber
class node_db_session,node_user_model,node_account_model,node_refresh_model toneMint
class node_user_schema,node_token_schema toneRose
class node_google toneIndigo
```

## Components

### API flows

- [FastAPI app](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/main.py): `app/main.py`
- [Password auth](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Google auth](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/routers/google_auth.py): `app/routers/google_auth.py`

### Identity security

- [Token and password security](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/core/security.py): `app/core/security.py`

### Persistence

- [Database session](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/database.py): `app/database.py`
- [User records](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/models/user.py): `app/models/user.py`
- [Provider accounts](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/models/AuthAccount.py): `app/models/AuthAccount.py`
- [Refresh-token records](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/models/refresh_token.py): `app/models/refresh_token.py`

### API contracts

- [User schemas](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/schemas/user.py): `app/schemas/user.py`
- [Token schema](https://github.com/ahmetfbalci/fastapi-jwt-auth/blob/main/app/schemas/token.py): `app/schemas/token.py`

### Other components

- **API client**
- **Google OAuth**
- **PostgreSQL**

## Connections

- API client → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Password auth: mounts router (evidence: `app/main.py`)
- FastAPI app → Google auth: mounts router (evidence: `app/main.py`)
- FastAPI app → Database session: creates tables (evidence: `app/main.py`)
- Password auth → User schemas: validates users (evidence: `app/routers/auth.py`)
- Password auth → Token schema: returns tokens (evidence: `app/routers/auth.py`)
- Google auth → Token schema: returns tokens (evidence: `app/routers/google_auth.py`)
- Password auth → Token and password security: uses security (evidence: `app/routers/auth.py`)
- Google auth → Token and password security: uses token functions (evidence: `app/routers/google_auth.py`)
- Token and password security → Database session: gets session (evidence: `app/core/security.py`)
- Token and password security → User records: loads current user (evidence: `app/core/security.py`)
- Password auth → Database session: gets session (evidence: `app/routers/auth.py`)
- Password auth → User records: queries and writes (evidence: `app/routers/auth.py`)
- Password auth → Refresh-token records: stores and revokes (evidence: `app/routers/auth.py`)
- Google auth → Database session: gets session (evidence: `app/routers/google_auth.py`)
- Google auth → User records: queries and creates (evidence: `app/routers/google_auth.py`)
- Google auth → Provider accounts: looks up and links (evidence: `app/routers/google_auth.py`)
- Google auth → Refresh-token records: stores refresh tokens (evidence: `app/routers/google_auth.py`)
- Google OAuth → Google auth: authorizes callback (evidence: `app/routers/google_auth.py`)
- Database session → PostgreSQL: connects to (evidence: `app/database.py`)
- User records → Database session: uses declarative base (evidence: `app/models/user.py`)
- Provider accounts → Database session: uses declarative base (evidence: `app/models/AuthAccount.py`)
- Refresh-token records → Database session: uses declarative base (evidence: `app/models/refresh_token.py`)
