How fastapi/full-stack-fastapi-template works
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: login.py Auth, users, and items · sdk.gen.ts Generated TypeScript SDK · compose.yml Compose deployment · __root.tsx Route shell and pages
Components 20
React dashboard
- Browser users
- React/Vite entry
frontend/src/main.tsx - Route shell and pages · Public auth and protected workspace routes.
frontend/src/routes/__root.tsx - Auth state and guard
frontend/src/hooks/useAuth.ts - Item and admin UI · Mutations for items and users.
frontend/src/components/Items/AddItem.tsx - Generated TypeScript SDK
frontend/src/client/sdk.gen.ts - Client generation
scripts/generate-client.sh
FastAPI backend
- FastAPI application
backend/app/main.py - Versioned API · Mounts API routes and interactive documentation.
backend/app/api/main.py - Auth, users, and items
backend/app/api/routes/login.py - Auth dependencies · Resolves current users and authorization before handlers.
backend/app/api/deps.py - JWT and password security
backend/app/core/security.py - CRUD layer
backend/app/crud.py - Account email templates · Password reset and new-account notifications.
backend/app/email-templates/reset_password.html
Data and migrations
- SQLModel contracts · Persisted entities plus request and response contracts.
backend/app/models.py - PostgreSQL · Production persistence store.
- Alembic migrations
backend/app/alembic/env.py
Runtime and delivery
- Compose deployment · Runs local/self-hosted services including PostgreSQL, Mailpit, and Traefik.
compose.yml - Backend container
backend/Dockerfile - Frontend container
frontend/Dockerfile.playwright
Connections 23
- 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