Repolode
Submit
zhanymkanov

zhanymkanov/fastapi-best-practices

Opinionated best practices and conventions for building production FastAPI applications, drawn from startup experience.

View on GitHub
Stars
18,217
Forks
1,329
Open issues
16
Last commit
2 months ago

What is it?

This guide collects opinionated conventions for building FastAPI backends in production. It covers how to structure a monolith with many domains, when to use async versus sync routes and dependencies, how to organize Pydantic models and settings, and how to layer dependencies for validation and reuse.

It also addresses data and tooling topics: SQL-first query design, Alembic migration rules, database naming conventions, using BackgroundTasks versus a real task queue, controlling API docs visibility, and writing async integration tests with httpx and dependency overrides. Code examples accompany most sections.

The content targets Python developers already familiar with FastAPI who want guidance on maintainable project layout and common pitfalls, such as blocking the event loop or misusing BackgroundTasks. A companion AGENTS.md file gives the same rules in a machine-readable form for AI coding agents.

Key features

  • 01Project layout guidance for organizing a monolith by domain modules.
  • 02Explanations of when sync and async routes and dependencies run in a threadpool.
  • 03Patterns for chaining and caching dependencies for request validation.
  • 04Pydantic conventions including a custom base model and split BaseSettings.
  • 05Guidance on SQL-first queries, Alembic migrations and database naming.
  • 06Testing setup with async httpx clients and dependency_overrides, plus ruff for linting and formatting.

Use cases

  • Structuring a growing FastAPI monolith with many domains and modules.
  • Onboarding developers onto a team's FastAPI conventions.
  • Reviewing async/sync choices to avoid blocking the event loop.
  • Giving AI coding agents consistent FastAPI rules via AGENTS.md.

Things to know

  • No license is specified in the project metadata.

Topics

#fastapi#python#best-practices#pydantic#sqlalchemy#async#backend-architecture

FAQ

What is fastapi-best-practices?
Opinionated best practices and conventions for building production FastAPI applications, drawn from startup experience. This guide collects opinionated conventions for building FastAPI backends in production. It covers how to structure a monolith with many domains, when to use async versus sync routes and dependencies, how to organize Pydantic models and settings, and how to layer dependencies for validation and reuse.
Is fastapi-best-practices free to use? What license does it have?
fastapi-best-practices has no declared license. Its code is public, but without a license you have no explicit permission to reuse it; ask the author before relying on it.
Is fastapi-best-practices still maintained?
Updated within 6 months. The last commit to fastapi-best-practices was on Aug 27, 2026.
What can I use fastapi-best-practices for?
Structuring a growing FastAPI monolith with many domains and modules. Onboarding developers onto a team's FastAPI conventions. Reviewing async/sync choices to avoid blocking the event loop. Giving AI coding agents consistent FastAPI rules via AGENTS.md.
Where can I get fastapi-best-practices?
The source code and installation instructions are on GitHub: https://github.com/zhanymkanov/fastapi-best-practices

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects