| name | fastapi-structure-guide |
| description | Trigger when the user wants to create a new FastAPI project, add new features, refactor code, or asks about architectural best practices. This skill enforces 2026 clean architecture with SQLModel, Repository Pattern, full async, and production-ready workflow. |
FastAPI Structure Guide (2026 Optimized Edition)
Intent
Use this guide whenever generating code for a FastAPI project, specifically when:
- Scaffolding a brand new project.
- Adding a new feature (e.g., "Add an Order module").
- Refactoring existing code to meet 2026 clean architecture standards.
You must strictly adhere to the Core Principles, Project Structure, Development Workflow, and Coding Rules defined below.
I. Core Principles
Before writing any code, follow these six guiding principles:
-
Separation of Concerns (Clean Architecture)
- API Layer: Only reception, validation, HTTP concerns.
- Service Layer: Pure business logic and orchestration.
- Repository Layer: All data access (SQL, caching, external services).
- DB/Model Layer: Data definition (SQLModel).
- Rule: Never put business logic or raw SQL in API routes or services.
-
Full Async First
- All routes, services, repositories must be
async def by default.
- Use
async_sessionmaker + await everywhere.
- Only use sync when absolutely necessary (e.g., legacy libs).
-
Repository Pattern + Dependency Injection
- Services never touch Session directly.
- Use FastAPI
Depends + Annotated for injection.
- Flow: DB Session → Repository → Service → API Route.
-
Mandatory Use of SQLModel
- All database models and base schemas must use SQLModel (Pydantic v2 + SQLAlchemy 2.0).
- One class serves as both DB table (
table=True) and API schema base.
- Never use raw SQLAlchemy + separate Pydantic models.
- Always consult
references/sqlmodel-reference.md for exact syntax, schema variants, relationships, and FastAPI integration patterns.
-
Config Centralization
- All config via Pydantic Settings v2 (
BaseSettings).
- Never hardcode secrets, URLs, or keys.
-
Mirrored & Layered Testing
tests/ mirrors app/ 1:1.
- Separate
unit/, integration/.
- Use SQLite in-memory + dependency overrides + pytest-asyncio.
II. Recommended Project Structure (2026 Standard)
my-fastapi-project/
├── app/ # Core Application
│ ├── __init__.py
│ ├── main.py # App factory + lifespan
│ ├── api/ # 🌐 API Layer
│ │ ├── __init__.py
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── api.py # Router aggregation
│ │ └── endpoints/
│ │ ├── __init__.py
│ │ ├── users.py
│ │ └── items.py
│ ├── core/ # ⚙️ Cross-cutting
│ │ ├── __init__.py
│ │ ├── config.py # Settings
│ │ ├── logging.py
│ │ ├── security.py
│ │ └── exceptions.py # Custom HTTP exceptions
│ ├── db/ # 🗄️ Database
│ │ ├── __init__.py
│ │ ├── session.py # async_sessionmaker
│ │ ├── models.py # SQLModel definitions (table=True)
│ │ └── alembic/ # Migrations
│ ├── schemas/ # 📝 API Schemas (DTOs)
│ │ ├── __init__.py
│ │ └── user.py # UserCreate, UserResponse, etc.
│ ├── repositories/ # 🗃️ Data Access Layer (NEW)
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── user_repository.py
│ │ └── item_repository.py
│ ├── services/ # 🧠 Business Logic
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── user_service.py
│ │ └── item_service.py
│ └── dependencies.py # Centralized Depends functions
├── tests/ # ✅ Tests (mirrored)
│ ├── __init__.py
│ ├── conftest.py
│ ├── unit/
│ └── integration/
│ └── api/
│ └── v1/
│ └── endpoints/
│ └── test_users.py
├── .env # Gitignored
├── .env.example
├── .gitignore
├── docker-compose.yaml
├── Dockerfile
├── pyproject.toml # uv + ruff + pyright + pytest-asyncio
└── README.md
Directory Responsibilities (Updated)
app/schemas/: API input/output models (inherits from SQLModel when possible).
app/repositories/: All DB operations, caching, external API calls. Thin wrapper around SQLModel.
app/services/: Business rules, orchestration, validation. Depends on repositories.
app/db/models.py: SQLModel classes with table=True.
app/core/exceptions.py: Custom exceptions + HTTPException handlers.
III. Creation Rules (Development Workflow)
When adding a new feature, follow these 6 Standard Steps in strict order:
Before Step A: Read references/sqlmodel-reference.md.
Step A: Database Model
Add SQLModel class in app/db/models.py (or split file if large).
Step B: API Schemas
Create app/schemas/resource.py (Create/Update/Response variants).
Step C: Repository
Create app/repositories/resource_repository.py (CRUD methods).
Step D: Service
Create app/services/resource_service.py (business logic using repository).
Step E: API Endpoint
Create app/api/v1/endpoints/resource.py (thin routes).
Step F: Registration & Testing
- Register router in
app/api/v1/api.py.
- Write mirrored tests in
tests/integration/.
IV. Coding Rules (2026 Modern Examples)
Rule 0: SQLModel Strict Compliance
All SQLModel code must exactly match patterns in references/sqlmodel-reference.md.
Any deviation must be rejected and corrected.
Rule 1: API Routes Must Be Thin & Async
@router.post("/users", response_model=UserResponse)
async def create_user(
user_in: UserCreate,
service: UserService = Depends(get_user_service),
):
return await service.create_user(user_in)
Rule 2: Repository Pattern (Data Access)
from sqlmodel.ext.async_session import AsyncSession
from sqlmodel import select
from app.db.models import User
class UserRepository:
def __init__(self, session: AsyncSession):
self.session = session
async def create(self, user: User) -> User:
self.session.add(user)
await self.session.commit()
await self.session.refresh(user)
return user
async def get_by_email(self, email: str) -> User | None:
statement = select(User).where(User.email == email)
result = await self.session.exec(statement)
return result.first()
Rule 3: Service Layer (Business Logic)
class UserService:
def __init__(self, repo: UserRepository):
self.repo = repo
async def create_user(self, data: UserCreate) -> User:
if await self.repo.get_by_email(data.email):
raise UserAlreadyExists()
user = User(**data.model_dump(exclude={"password"}))
return await self.repo.create(user)
Rule 4: Dependencies (centralized)
from fastapi import Depends
from sqlmodel.ext.async_session import async_sessionmaker
async def get_db() -> AsyncSession:
async with sessionmaker() as session:
yield session
def get_user_repository(db: AsyncSession = Depends(get_db)) -> UserRepository:
return UserRepository(db)
def get_user_service(repo: UserRepository = Depends(get_user_repository)) -> UserService:
return UserService(repo)
Rule 5: SQLModel Usage
from sqlmodel import SQLModel, Field
class User(SQLModel, table=True):
id: int | None = Field(default=None, primary_key=True)
email: str = Field(index=True, unique=True)
hashed_password: str