zhanymkanov/fastapi-best-practices

★ 17,245Audience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((fastapi-best-practices))
    What it does
      FastAPI conventions guide
      Project structure
      Production patterns
    Topics Covered
      Async vs sync routes
      Pydantic validation
      Database migrations
      Dependency injection
    Use Cases
      New project scaffold
      Code review guide
      AI coding rules file
    Audience
      Python developers
      Backend engineers
      API builders

mindmap root((fastapi-best-practices)) What it does FastAPI conventions guide Project structure Production patterns Topics Covered Async vs sync routes Pydantic validation Database migrations Dependency injection Use Cases New project scaffold Code review guide AI coding rules file Audience Python developers Backend engineers API builders

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Set up a new FastAPI project with a domain-driven folder structure that scales as the codebase grows

USE CASE 2

Identify and fix blocking operations accidentally placed inside async route handlers that silently slow the whole server

USE CASE 3

Standardise database naming conventions and add Alembic migrations to an existing FastAPI app

USE CASE 4

Create an AGENTS.md companion file so AI coding assistants follow the same FastAPI conventions as the team

Tech stack

PythonFastAPIPydanticAlembicruff

Getting it running

Difficulty · easy Time to first run · 5min

In plain English

This repository is an opinionated guide to building production-ready web services with FastAPI. FastAPI is a Python framework for creating web APIs, and this guide collects the lessons the author and their team learned from running real systems at their startup over several years. It is not a tutorial that teaches FastAPI from scratch, it is a checklist of conventions you can copy or adapt. The guide is organised by topic. It opens with a suggested project structure inspired by Netflix's Dispatch project, where each business domain (auth, posts, aws, and so on) lives in its own folder inside a top-level src directory, with consistent file names for routers, Pydantic schemas, database models, dependencies, services, configs and exceptions. It then explains the difference between async and sync routes, and shows what happens if you accidentally do a blocking operation inside an async route, the whole server stops handling requests until that operation finishes. Other sections cover how to use Pydantic for validation and settings, how to write reusable dependencies, REST conventions, when to use FastAPI's BackgroundTasks versus a real task queue, database naming conventions and Alembic migrations, treating SQL as the source of truth before Pydantic, and adopting the ruff linter. Someone would actually use this if they are starting a new FastAPI codebase and want a sensible default structure, or if their existing project has grown messy and they want patterns to lean on. There is also an AGENTS.md companion file with the same rules in a terse format aimed at AI coding agents. The full README is longer than what was provided.

Copy-paste prompts

Prompt 1

Using the fastapi-best-practices structure, scaffold a new FastAPI project with separate routers for auth and posts, Pydantic schemas, and an Alembic migration setup.

Prompt 2

Review my FastAPI route handlers and flag any that run blocking database calls inside async functions, following the fastapi-best-practices guide.

Prompt 3

Convert my FastAPI project's flat file layout to the domain-driven src/ structure recommended in fastapi-best-practices.

Prompt 4

Using the fastapi-best-practices dependency pattern, refactor my JWT auth into a reusable FastAPI dependency I can attach to any router.

Prompt 5

Add a ruff linter config to my FastAPI project following the fastapi-best-practices recommendations and fix any violations it finds.

Open on GitHub → Explain another repo

← zhanymkanov on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.