Skip to main content

Overview

The Full Stack FastAPI Template is a production-ready blueprint for building modern web applications. It provides a pre-configured stack featuring a FastAPI backend, a React frontend, and a PostgreSQL database, all orchestrated with Docker.

This project exists to eliminate the "blank page" problem for full-stack developers. Instead of spending days setting up authentication, database migrations, and CI/CD pipelines, you can start writing business logic on minute one with a stack that follows industry best practices.

Core Concepts​

  • Type Safety Everywhere: By using SQLModel on the backend and generating a TypeScript client for the frontend, types flow from your database schema all the way to your React components.
  • Batteries Included: Authentication (JWT), password recovery, user management, and email integration are built-in and ready to use.
  • Developer Experience (DX): Features like live-reload for both frontend and backend, a dedicated database management UI (Adminer), and local email testing (Mailcatcher) make development seamless.
  • Deployment First: The template includes a production-ready compose.yml with Traefik for automatic HTTPS via Let's Encrypt.

How It Works​

  1. Backend: A FastAPI application uses SQLModel to define data structures that serve as both database tables and API schemas.
  2. Database: PostgreSQL stores your data, with Alembic handling versioned migrations to keep your schema in sync.
  3. Frontend: A React SPA built with Vite uses TanStack Router for navigation and TanStack Query for efficient data fetching.
  4. Client Generation: A script automatically generates a TypeScript API client from the backend's OpenAPI schema, ensuring the frontend always knows exactly what the backend expects.
  5. Orchestration: Docker Compose manages the lifecycle of the API, frontend, database, and supporting services (proxy, admin tools).

Use Cases​

Defining a New Data Model​

Add a new entity to your system by defining a single class that handles both database storage and API validation.

# backend/app/models.py
from sqlmodel import Field, SQLModel
import uuid

class Item(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    title: str = Field(min_length=1, max_length=255)
    description: str | None = None
    owner_id: uuid.UUID = Field(foreign_key="user.id")

Creating a Protected API Endpoint​

Use dependency injection to secure routes and access the current authenticated user.

# backend/app/api/routes/items.py
from app.api.deps import CurrentUser, SessionDep
from app.models import Item, ItemCreate

@router.post("/", response_model=Item)
def create_item(*, session: SessionDep, user: CurrentUser, item_in: ItemCreate):
    item = Item.model_validate(item_in, update={"owner_id": user.id})
    session.add(item)
    session.commit()
    return item

Fetching Data in the Frontend​

Use the generated client and TanStack Query for type-safe data fetching with built-in caching.

// frontend/src/components/Items/ItemsTable.tsx
import { useQuery } from "@tanstack/react-query"
import { ItemsService } from "../../client"

const { data: items } = useQuery({
  queryKey: ["items"],
  queryFn: () => ItemsService.readItems({ skip: 0, limit: 10 }),
})

When to Use​

  • Use this template if you are building a SaaS, a dashboard, or a complex internal tool that requires robust authentication and a relational database.
  • Use this template if you value type safety and want to catch errors at compile-time rather than runtime.
  • Do not use this template if you are building a simple static site, a tiny microservice with a single endpoint, or if you strongly prefer NoSQL databases.

Stack Compatibility​

  • Backend: Python 3.10+, FastAPI, SQLModel, Pydantic, Alembic.
  • Frontend: React 19, TypeScript, Vite, TanStack Query/Router, Tailwind CSS.
  • Infrastructure: Docker, PostgreSQL, Traefik, Sentry.
  • Testing: Pytest (Backend), Playwright (E2E).

Getting Started Pointers​

Limitations​

  • Opinionated Structure: The project enforces a specific directory structure and library choice (e.g., TanStack over Redux).
  • Relational Focus: While you can add other databases, the core logic is built around PostgreSQL and SQLModel.
  • Learning Curve: New developers may need time to understand the interaction between Docker, Traefik, and the client generation scripts.