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 is not a UI string to be translated from Italian into English.

Project status

Description

FastAPI From Scratch is the Python equivalent of Spring Boot From Scratch, offering a progressive approach with the same domain application (a shared task management system), philosophy ('build-your-own'), and adapted to the Python ecosystem and modern patterns. The journey covers step-by-step: setting up pyproject.toml + uv (with documented fallbacks to pip/poetry for traditional tooling), modular FastAPI app structure with APIRouter, deep Pydantic v2 validation with discriminated unions, custom validators, and computed fields, native dependency injection (Depends) for auth/DB/settings, async database with SQLAlchemy 2.0 + asyncpg, Alembic for versioned migrations, JWT authentication with python-jose + passlib + argon2, comprehensive testing with pytest + httpx AsyncClient + factory_boy + pytest-asyncio, production-grade observability with structlog + Prometheus FastAPI Instrumentator + custom healthcheck, deployment with Uvicorn + Gunicorn workers + optimized Dockerfile. Each step is a Git branch with optional exercises, reference solution, and ADR for documenting choices. The documentation includes MkDocs Material with sequence diagram async (event loop, await yields, task scheduling, semaphore patterns), often the main point of confusion for those coming from Flask synchronous, Django, or Node.js. The project is MIT-licensed, optimized for cloning and use as a production-ready Python microservice scaffold, aligned with the portfolio stack: the ml-service pattern (FastAPI + Ollama + RediSearch) is cited as a real-world production case study on VPS Hetzner.

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.

Angular + Spring Boot on top of a PostgreSQL database hosted in the cloud via AWS or Google Cloud Platform

  • 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
    • Integration test with pytest and asynchronous code
  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 with four commands, requires Docker and GitHub Desktop is not required but a git client like SourceTree or Visual Studio Code's built-in one will do just fine though. 

# 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
← Back to list⭐ View on GitHub