WIP MITInstructors

FastAPI From Scratch

Build an async, production-ready API with FastAPI, Pydantic, and SQLAlchemy 2

Status
WIP
License
MIT
Category
Instructors
Updated
GitHub source

Project status

Description

FastAPI From Scratch is the Python twin of Spring Boot From Scratch: same progressive approach, same application domain (a shared task management system), same 'build-your-own' philosophy, but adapted to the Python ecosystem and to modern FastAPI 0.115+ patterns with Pydantic v2 and SQLAlchemy 2.0 async. The path covers, step by step: pyproject.toml + uv setup (with a documented fallback to pip/poetry for those who prefer traditional tooling), modular FastAPI app structure with APIRouter to separate bounded contexts, deep Pydantic v2 validation with discriminated unions, custom validators and computed fields, FastAPI-native dependency injection (Depends) for auth/DB/settings, async database with SQLAlchemy 2.0 + asyncpg (native PostgreSQL driver), Alembic for versioned migrations, JWT authentication with python-jose + passlib + argon2, a complete testing pyramid with pytest + httpx AsyncClient + factory_boy + pytest-asyncio, production-grade observability with structlog + Prometheus FastAPI Instrumentator + custom healthcheck, deployment with Uvicorn + Gunicorn workers + an optimized multi-stage Dockerfile. Each step is a git branch with optional exercises, a reference solution and an ADR documenting the choices. The MkDocs Material documentation includes async sequence diagrams (event loop, await yields, task scheduling, semaphore patterns), which are often the main point of confusion for people coming from synchronous Flask, Django or Node.js. The project is MIT-licensed, optimized to be cloned and used as a scaffold for production-ready Python microservices. Aligned with the portfolio stack: the ml-service/ pattern (FastAPI + Ollama + RediSearch) is cited as a real production case study on a Hetzner VPS.

Key Features

  • Async/Await First-Class

    Every endpoint is async, SQLAlchemy 2.0 async session, httpx AsyncClient for downstream calls, sequence diagrams of event loops explained.

  • Deep Pydantic v2 validation

    Custom validators, discriminated unions, computed fields, JSON schema export, alias generator for snake_case to camelCase API contract.

  • Dependency Injection - FastAPI Native

    Pattern depends on authentication, database session, setting injection, sub-dependency, and test-time dependency override.

  • PostgreSQL 2.0 async + Alembic

    Mapped [Type] type-annotated, async session with context manager, eager loading strategy, Alembic auto-generate migrations.

  • Complete testing pyramid

    Concise unit tests with pytest, integration tests using TestClient and httpx, async fixtures, factory boy for test data, 80%+ coverage with pytest-cov.

  • OpenAPI 3.1 automatically generated

    Rich OpenAPI schema thanks to Pydantic, response_model and status_code for each endpoint, semantic tags and summaries, Redoc UI deployment.

  • Production-Grade Observability

    Concise logging with request_id and Prometheus metrics via prometheus-fastapi-instrumentator, custom health check endpoint.

Tech stack

  • FastAPI 0.115+
  • Python 3.12
  • Pydantic v2
  • SQLAlchemy 2.0
  • Alembic
  • asyncpg
  • pytest
  • httpx
  • uv
  • structlog

Use cases

  • Python developers who want to learn FastAPI with modern patterns (Pydantic v2, SQLAlchemy 2 async)
  • Developers using Flask/Django who want to migrate to async and understand the event loop without magic.
  • Bootcamps and courses looking for updated FastAPI educational material up to 2026
  • Team looking for a clean scaffold for new Python microservices production-ready

Road Map

  1. v0.1.0Scheduled

    Foundation: FastAPI + Pydantic v2

    • Setup pyproject.toml and uv.
    • Modular API Router Structure
    • Pydantic v2 schemas and validators
    • Sync endpoint baseline + OpenAPI documentation
  2. v0.5.0Scheduled

    Asynchronous Database Authentication

    • PostgreSQL 2.0 async + Alembic migrations
    • JWT authentication with Python-JOSE and Passlib
    • Dependency Injection Patterns
    • Async pytest integration tests
  3. v1.0.0Scheduled

    Observability + Deployment

    • Log structure + Prometheus instrumentation tool
    • Dockerfile multi-stage with Uvicorn and Gunicorn
    • Deploy Guide for VPS Systemd Unit
    • Complete MkDocs Documentation

Who is it for

  • Tech enthusiasts
  • Junior/ Mid-Level Developer

Quick start

Start the project locally in just a few commands. 

# Quick start (work-in-progress, repo non ancora pubblicato)
# git clone https://github.com/<tba>/fastapi-from-scratch.git
# cd fastapi-from-scratch
# uv venv && source .venv/bin/activate
# uv pip install -e .[dev]
# uvicorn app.main:create_app --factory --reload

Contribute to the project

FastAPI From Scratch is open source. Open an issue, propose a pull request or leave a star on GitHub: every contribution, no matter how small, is welcome.

  • ⭐ Leave a star if it's useful
  • 🐛 Report bugs or suggest features via issue
  • 🔧 Send a pull request with fixes or improvements
  • 📣 Share the project if you find it interesting
Star on GitHubOpen an issuePull request
← ⭐ View on GitHub