develop-fastapi-app

When to use this skill

Use this skill when:

• Starting a new FastAPI project
• Refactoring existing FastAPI applications
• Implementing REST APIs with Python
• Working with async/await patterns in web services
• Setting up database models and migrations
• Writing tests for FastAPI endpoints
• Configuring dependency injection patterns
• Optimizing API performance and code quality

Project Structure

Organize projects by domain rather than file type for better scalability:

fastapi-project/
├── app/
│   ├── schemas/                 # data structure and constraints
│   ├── models/                  # schema with behavior
│   ├── managers/                # domain orchestrator
│   ├── exceptions/              # business exception
│   ├── routes/                  # domain orchestrator
│   ├── settings.py              # application global settings
│   ├── engine.py                # database engine
├── utils/
├── libs/
├── tests/
│   ├── conftest.py
│   ├── <by_domain>/test_<xxx>.py
├── migrations/
├── scripts/
├── docs/
├── .env
├── .env.example
├── logging.ini
├── pyproject.toml
└── run.py                       # FastAPI app

File Templates:

• route.py - Router module with endpoints
• schemas.py - Pydantic request/response schemas
• models.py - SQLAlchemy database models
• dependencies.py - Validation dependencies
• manager.py - Domain orchestrator/service
• exceptions.py - Module-specific exceptions
• run.py - Main application file
• settings.py - Global configuration
• engine.py - Database engine setup

Notes:

• Store all domain modules inside app/ folder
• Each subfolder (schemas/, models/, managers/, routes/) is organized by domain
  • e.g., app/schemas/posts.py, app/managers/posts_manager.py, app/routes/posts.py
• Import from other packages with explicit module names

References

Read revelant references before you really start your task:

• API Best Practices
• Async Patterns
• Pydantic Best Practices
• Dependencies Guide
• Database Operations
• Testing

General Best Practices

• Use Ruff for fast linting and formatting:

ruff check --fix src
ruff format src