# fastapi/full-stack-fastapi-template architecture

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

- Interactive diagram: https://gitdiagram.com/fastapi/full-stack-fastapi-template
- Repository: https://github.com/fastapi/full-stack-fastapi-template
- Video tour (about a minute): https://gitdiagram.com/fastapi/full-stack-fastapi-template/video

## Overview

#### Purpose and Top-Level Entry Points
A full-stack template providing a JWT-secured FastAPI API, PostgreSQL persistence, and React administrative dashboard for users and generic items. Backend startup is `backend/app/main.py`; API composition is `backend/app/api/main.py`. The browser app starts at `frontend/src/main.tsx` and route definitions begin at `frontend/src/routes/__root.tsx`.

#### Backend API and Request Boundary
FastAPI mounts versioned API routes and provides interactive API documentation. Route modules separate authentication, user management, item CRUD, private/authenticated endpoints, and operational utilities:
- `backend/app/api/main.py`
- `backend/app/api/routes/login.py`
- `backend/app/api/routes/users.py`
- `backend/app/api/routes/items.py`

Dependencies in `backend/app/api/deps.py` enforce current-user and authorization boundaries before route handlers access application data.

#### Domain, Persistence, and Schema Evolution
SQLModel models define persisted entities and request/response contracts, while CRUD isolates database operations from HTTP handlers. PostgreSQL is the intended production datastore; Alembic owns migration history and database schema upgrades.
- `backend/app/models.py`
- `backend/app/crud.py`
- `backend/app/core/db.py`
- `backend/app/alembic/env.py`
- `backend/app/alembic/versions/e2412789c190_initialize_models.py`

Application initialization and seed behavior are represented by `backend/app/initial_data.py`.

#### Identity, Security, and Account Lifecycle
Authentication uses password hashing and JWTs. Login, password recovery/reset, registration, self-service profile/password changes, and administrator user management span API routes and shared security/configuration code.
- `backend/app/core/security.py`
- `backend/app/core/config.py`
- `backend/app/api/routes/login.py`
- `backend/app/api/routes/users.py`

Email delivery supports recovery and account notifications. HTML templates are runtime backend assets, with corresponding React Email source templates available for maintaining their design.
- `backend/app/email-templates/reset_password.html`
- `backend/app/email-templates/new_account.html`
- `packages/react-email/emails/reset_password.tsx`

#### Frontend Application and Navigation
The frontend is a TypeScript React/Vite single-page dashboard using route-level layouts to separate authenticated workspace pages from public auth flows. The protected layout contains dashboard, item, admin, and settings areas.
- `frontend/src/routes/_layout.tsx`
- `frontend/src/routes/_layout/items.tsx`
- `frontend/src/routes/_layout/admin.tsx`
- `frontend/src/routes/login.tsx`

Feature components implement item and user mutations; shared sidebar/auth-layout components define the main application shell.
- `frontend/src/components/Items/AddItem.tsx`
- `frontend/src/components/Admin/AddUser.tsx`
- `frontend/src/components/Common/AuthLayout.tsx`

#### Client/API Integration Flow
The frontend auth hook manages browser-side authentication state and drives protected navigation. UI components call a generated TypeScript SDK derived from the FastAPI OpenAPI contract, making the API schema the principal frontend/backend integration boundary.
- `frontend/src/hooks/useAuth.ts`
- `frontend/src/client/client.gen.ts`
- `frontend/src/client/sdk.gen.ts`
- `scripts/generate-client.sh`

Typical flow: browser route → auth guard/component → generated API client → FastAPI dependency/authentication → route handler → CRUD/SQLModel → PostgreSQL → typed response → UI state and notifications.

#### Runtime, Delivery, and Local Infrastructure
Backend runs in Python/FastAPI; frontend is built with Node/Bun-era package tooling and Vite, then is intended to be served on the same domain as the API. Docker Compose supports local and self-hosted operation with PostgreSQL, Mailpit for development email capture, and Traefik reverse proxy/automatic HTTPS in deployment configurations.
- `compose.yml`
- `compose.deploy.yml`
- `backend/Dockerfile`
- `frontend/Dockerfile.playwright`

GitHub Actions defines backend, Compose, browser, and deployment automation under `.github/workflows/`; FastAPI Cloud is the managed deployment target.

Main entry points: [`backend/app/api/routes/login.py`](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/routes/login.py) (Auth, users, and items), [`frontend/src/client/sdk.gen.ts`](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/client/sdk.gen.ts) (Generated TypeScript SDK), [`compose.yml`](https://github.com/fastapi/full-stack-fastapi-template/blob/master/compose.yml) (Compose deployment), [`frontend/src/routes/__root.tsx`](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/routes/__root.tsx) (Route shell and pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React dashboard"]
  node_browser(("Browser users<br/>client"))
  node_frontend_entry["React/Vite entry<br/>frontend entry<br/>[main.tsx]"]
  node_route_shell["Route shell and pages<br/>React routes<br/>[__root.tsx]"]
  node_auth_hook["Auth state and guard<br/>React hook<br/>[useAuth.ts]"]
  node_feature_ui["Item and admin UI<br/>React features<br/>[AddItem.tsx]"]
  node_typescript_sdk["Generated TypeScript SDK<br/>OpenAPI client<br/>[sdk.gen.ts]"]
  node_client_generator["Client generation<br/>generation script<br/>[generate-client.sh]"]
end

subgraph group_backend["FastAPI backend"]
  node_fastapi_app["FastAPI application<br/>backend entry<br/>[main.py]"]
  node_api_composition["Versioned API<br/>route composition<br/>[main.py]"]
  node_api_routes["Auth, users, and items<br/>route handlers<br/>[login.py]"]
  node_auth_dependencies["Auth dependencies<br/>request boundary<br/>[deps.py]"]
  node_security["JWT and password security<br/>security service<br/>[security.py]"]
  node_crud["CRUD layer<br/>data access<br/>[crud.py]"]
  node_email_assets["Account email templates<br/>runtime templates"]
end

subgraph group_data["Data and migrations"]
  node_models["SQLModel contracts<br/>domain models<br/>[models.py]"]
  node_postgres[("PostgreSQL<br/>database")]
  node_alembic["Alembic migrations<br/>schema evolution<br/>[env.py]"]
end

subgraph group_delivery["Runtime and delivery"]
  node_compose["Compose deployment<br/>container orchestration<br/>[compose.yml]"]
  node_backend_image["Backend container<br/>Docker image"]
  node_frontend_image["Frontend container<br/>Docker image"]
end

node_browser -->|"loads"| node_frontend_entry
node_frontend_entry -->|"renders"| node_route_shell
node_route_shell -->|"protects routes with"| node_auth_hook
node_route_shell -->|"hosts"| node_feature_ui
node_auth_hook -->|"authenticates via"| node_typescript_sdk
node_feature_ui -->|"calls"| node_typescript_sdk
node_client_generator -.->|"generates from OpenAPI"| node_typescript_sdk
node_typescript_sdk -->|"HTTP API calls"| node_fastapi_app
node_fastapi_app -->|"composes"| node_api_composition
node_api_composition -->|"mounts"| node_api_routes
node_api_routes -->|"enforces"| node_auth_dependencies
node_auth_dependencies -->|"validates JWTs with"| node_security
node_api_routes -->|"uses"| node_crud
node_crud -->|"uses contracts"| node_models
node_crud -->|"reads and writes"| node_postgres
node_alembic -.->|"derives schema from"| node_models
node_alembic -->|"upgrades"| node_postgres
node_api_routes -->|"sends account emails"| node_email_assets
node_compose -->|"runs"| node_postgres
node_backend_image -->|"packages"| node_fastapi_app
node_frontend_image -->|"packages"| node_frontend_entry
node_compose -->|"orchestrates"| node_backend_image
node_compose -->|"orchestrates"| node_frontend_image

click node_frontend_entry "https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/main.tsx"
click node_route_shell "https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/routes/__root.tsx"
click node_auth_hook "https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/hooks/useAuth.ts"
click node_feature_ui "https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/components/Items/AddItem.tsx"
click node_typescript_sdk "https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/client/sdk.gen.ts"
click node_client_generator "https://github.com/fastapi/full-stack-fastapi-template/blob/master/scripts/generate-client.sh"
click node_fastapi_app "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/main.py"
click node_api_composition "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/main.py"
click node_api_routes "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/routes/login.py"
click node_auth_dependencies "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/deps.py"
click node_security "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/core/security.py"
click node_crud "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/crud.py"
click node_models "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/models.py"
click node_alembic "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/alembic/env.py"
click node_email_assets "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/email-templates/reset_password.html"
click node_compose "https://github.com/fastapi/full-stack-fastapi-template/blob/master/compose.yml"
click node_backend_image "https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/Dockerfile"
click node_frontend_image "https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/Dockerfile.playwright"

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_browser,node_frontend_entry,node_route_shell,node_auth_hook,node_feature_ui,node_typescript_sdk,node_client_generator toneBlue
class node_fastapi_app,node_api_composition,node_api_routes,node_auth_dependencies,node_security,node_crud,node_email_assets toneAmber
class node_models,node_postgres,node_alembic toneMint
class node_compose,node_backend_image,node_frontend_image toneRose
```

## Components

### React dashboard

- **Browser users**: client
- [React/Vite entry](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/main.tsx): frontend entry · `frontend/src/main.tsx`
- [Route shell and pages](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/routes/__root.tsx): React routes · Public auth and protected workspace routes. · `frontend/src/routes/__root.tsx`
- [Auth state and guard](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/hooks/useAuth.ts): React hook · `frontend/src/hooks/useAuth.ts`
- [Item and admin UI](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/components/Items/AddItem.tsx): React features · Mutations for items and users. · `frontend/src/components/Items/AddItem.tsx`
- [Generated TypeScript SDK](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/src/client/sdk.gen.ts): OpenAPI client · `frontend/src/client/sdk.gen.ts`
- [Client generation](https://github.com/fastapi/full-stack-fastapi-template/blob/master/scripts/generate-client.sh): generation script · `scripts/generate-client.sh`

### FastAPI backend

- [FastAPI application](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/main.py): backend entry · `backend/app/main.py`
- [Versioned API](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/main.py): route composition · Mounts API routes and interactive documentation. · `backend/app/api/main.py`
- [Auth, users, and items](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/routes/login.py): route handlers · `backend/app/api/routes/login.py`
- [Auth dependencies](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/api/deps.py): request boundary · Resolves current users and authorization before handlers. · `backend/app/api/deps.py`
- [JWT and password security](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/core/security.py): security service · `backend/app/core/security.py`
- [CRUD layer](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/crud.py): data access · `backend/app/crud.py`
- [Account email templates](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/email-templates/reset_password.html): runtime templates · Password reset and new-account notifications. · `backend/app/email-templates/reset_password.html`

### Data and migrations

- [SQLModel contracts](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/models.py): domain models · Persisted entities plus request and response contracts. · `backend/app/models.py`
- **PostgreSQL**: database · Production persistence store.
- [Alembic migrations](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/app/alembic/env.py): schema evolution · `backend/app/alembic/env.py`

### Runtime and delivery

- [Compose deployment](https://github.com/fastapi/full-stack-fastapi-template/blob/master/compose.yml): container orchestration · Runs local/self-hosted services including PostgreSQL, Mailpit, and Traefik. · `compose.yml`
- [Backend container](https://github.com/fastapi/full-stack-fastapi-template/blob/master/backend/Dockerfile): Docker image · `backend/Dockerfile`
- [Frontend container](https://github.com/fastapi/full-stack-fastapi-template/blob/master/frontend/Dockerfile.playwright): Docker image · `frontend/Dockerfile.playwright`

## Connections

- Browser users → React/Vite entry: loads
- React/Vite entry → Route shell and pages: renders
- Route shell and pages → Auth state and guard: protects routes with
- Route shell and pages → Item and admin UI: hosts
- Auth state and guard → Generated TypeScript SDK: authenticates via
- Item and admin UI → Generated TypeScript SDK: calls
- Client generation → Generated TypeScript SDK: generates from OpenAPI
- Generated TypeScript SDK → FastAPI application: HTTP API calls
- FastAPI application → Versioned API: composes
- Versioned API → Auth, users, and items: mounts
- Auth, users, and items → Auth dependencies: enforces
- Auth dependencies → JWT and password security: validates JWTs with
- Auth, users, and items → CRUD layer: uses
- CRUD layer → SQLModel contracts: uses contracts
- CRUD layer → PostgreSQL: reads and writes
- Alembic migrations → SQLModel contracts: derives schema from
- Alembic migrations → PostgreSQL: upgrades
- Auth, users, and items → Account email templates: sends account emails
- Compose deployment → PostgreSQL: runs
- Backend container → FastAPI application: packages
- Frontend container → React/Vite entry: packages
- Compose deployment → Backend container: orchestrates
- Compose deployment → Frontend container: orchestrates
