FastAPI Template Skill

Generate production-ready FastAPI CRUD modules following a simplified architecture with CRUD helpers.

When to Use This Skill

Use this skill when asked to:

•Create a new FastAPI entity/module (router, CRUD helpers, schemas)
•Add CRUD endpoints to an existing FastAPI application
•Generate reusable query functions following the CRUD helper pattern
•Build REST APIs with SQLAlchemy and Pydantic

Architecture Overview

code

Primary Pattern (most endpoints):
┌─────────────────────────────────────────────────────────────┐
│                    HTTP Request                              │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Router (api/routers/setting/{entity}_router.py)            │
│  • Endpoint definitions                                      │
│  • Request/Response validation                               │
│  • session: SessionDep                                       │
│  • Delegates to Service/Controller for most operations       │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Service/Controller (api/services/ or api/controllers/)      │
│  • Business logic, validation, orchestration                 │
│  • External integrations (AD/LDAP, email, Redis, SMS)       │
│  • Cross-cutting concerns (audit, notifications)             │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  CRUD Helper (api/crud/{entity}.py) — reusable queries       │
│  • Plain async functions (no classes)                        │
│  • Session as first parameter                                │
│  • flush() not commit()                                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Model (db/model.py) + Schemas                               │
│  • SQLModel ORM models                                       │
│  • api/schemas/ (domain) + api/http_schema/ (request/resp)   │
│  • Pydantic DTOs with CamelModel                             │
└─────────────────────────────────────────────────────────────┘

Secondary Pattern (simple entities like schedulers, OUs, domain-users):
┌─────────────────────────────────────────────────────────────┐
│  Router → CRUD helper / Direct queries → Model               │
│  Use only for simple entities with no business logic         │
└─────────────────────────────────────────────────────────────┘

File Structure

code

api/
├── routers/
│   └── setting/
│       └── {entity}_router.py      # Router with endpoints
├── crud/
│   ├── __init__.py                  # Re-exports all CRUD helpers
│   └── {entity}.py                  # Reusable query functions (3+ uses)
├── services/
│   └── {entity}_service.py          # ONLY for external integrations
├── schemas/
│   ├── _base.py                     # CamelModel base class
│   └── {entity}_schema.py           # Domain schemas
└── http_schema/
    └── {entity}_schema.py           # Request/response Pydantic DTOs

db/
└── model.py                         # SQLModel ORM models

core/
├── dependencies.py                  # SessionDep, CurrentUserDep
├── app_setup/
│   └── routers_group/
│       └── setting_routers.py       # Router registration
└── exceptions.py                    # DetailedHTTPException

Core Principles

1. Single Session Per Request

Every request uses exactly ONE database session via typed dependency:

python

@router.post("/items")
async def create_item(
    item_create: ItemCreate,
    session: SessionDep,  # Typed dependency - NOT Depends(get_session)
):
    item = Item(**item_create.model_dump())
    session.add(item)
    await session.commit()
    await session.refresh(item)
    return item

2. Session Flow

code

Simple:
Endpoint (SessionDep) → Direct query OR CRUD helper → Database

Complex:
Endpoint (SessionDep) → Service (receives session) → CRUD helper → Database

3. CamelModel for API Responses

All schemas inherit from CamelModel for automatic snake_case to camelCase conversion:

python

class ItemResponse(CamelModel):
    item_id: int        # Python: snake_case
    created_at: datetime
    # JSON output: {"itemId": 1, "createdAt": "..."}

4. Domain Exceptions

Use DetailedHTTPException for errors:

python

from api.exceptions import DetailedHTTPException
from fastapi import status

raise DetailedHTTPException(
    status_code=status.HTTP_404_NOT_FOUND,
    detail=f"Item not found with ID: {item_id}",
)

Generation Order

When creating a new entity, generate files in this order:

•Model (db/model.py) - Add SQLModel model
•Schemas (api/schemas/{entity}_schema.py + api/http_schema/{entity}_schema.py) - Pydantic DTOs
•CRUD helpers (api/crud/{entity}.py) - Only if queries are reused 3+ times
•Router (api/routers/setting/{entity}_router.py) - API endpoints
•Register router in core/app_setup/routers_group/setting_routers.py

Quick Reference

CRUD Helper Pattern

•Plain async functions (no classes)
•Session as first parameter
•flush() not commit() - caller commits
•Only create when query is reused 3+ times
•Import as: from api.crud import items as items_crud

Service/Controller Pattern (Primary)

•Most routers delegate to a Service or Controller class
•Business logic, validation, orchestration
•External integrations (AD, email, Redis, SMS)
•Uses CRUD helpers for database access (not repositories)
•Session passed as parameter

Router Pattern

•Use SessionDep typed dependency
•Most routers delegate to Service/Controller
•Direct queries only for simple entities (schedulers, OUs, domain-users)
•Import CRUD helpers for reusable queries
•Path: api/routers/setting/{entity}_router.py
•Registration: core/app_setup/routers_group/setting_routers.py

References

See the references/ directory for detailed patterns:

Core Patterns

•model-pattern.md - SQLAlchemy models
•schema-pattern.md - Pydantic DTO patterns
•crud-helper-pattern.md - Reusable query functions (replaces repository pattern)
•service-pattern.md - External integrations and complex orchestration
•router-pattern.md - API endpoints with SessionDep

Advanced Patterns

•file-upload-pattern.md - File uploads with UploadFile, validation, S3
•testing-pattern.md - pytest fixtures, async tests, dependency overrides
•response-types-pattern.md - HTML, file downloads, streaming, redirects
•middleware-pattern.md - Security headers, correlation ID, timing, logging
•form-data-pattern.md - Form handling, OAuth2 password flow, headers, cookies