davila7--claude-code-templates/cli-tool/templates/python/examples/fastapi-app/CLAUDE.md

FastAPI Project Configuration

This file provides specific guidance for FastAPI web application development using Claude Code.

Project Overview

This is a FastAPI application project optimized for modern API development with automatic documentation, type hints, and async support.

FastAPI-Specific Development Commands

Project Management

• uvicorn app.main:app --reload - Start development server with auto-reload
• uvicorn app.main:app --host 0.0.0.0 --port 8000 - Start server on all interfaces
• uvicorn app.main:app --workers 4 - Start with multiple workers

Database Management

• alembic init alembic - Initialize Alembic migrations
• alembic revision --autogenerate -m "message" - Create migration
• alembic upgrade head - Apply migrations
• alembic downgrade -1 - Rollback one migration

Development Tools

• python -m pytest - Run tests
• python -m pytest --cov=app - Run tests with coverage
• mypy app/ - Type checking
• black app/ - Code formatting

FastAPI Project Structure

myproject/
├── app/                        # Application package
│   ├── __init__.py
│   ├── main.py                # FastAPI application
│   ├── core/                  # Core configuration
│   │   ├── __init__.py
│   │   ├── config.py         # Settings
│   │   └── security.py       # Authentication
│   ├── api/                   # API routes
│   │   ├── __init__.py
│   │   ├── deps.py           # Dependencies
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── api.py        # API router
│   │       └── endpoints/
│   ├── models/                # Database models
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── user.py
│   ├── schemas/               # Pydantic schemas
│   │   ├── __init__.py
│   │   └── user.py
│   ├── repositories/          # Data access layer
│   │   ├── __init__.py
│   │   └── user.py
│   ├── services/              # Business logic
│   │   ├── __init__.py
│   │   └── auth.py
│   └── db/                    # Database configuration
│       ├── __init__.py
│       └── database.py
├── alembic/                   # Database migrations
├── tests/                     # Test files
├── requirements.txt           # Dependencies
└── docker-compose.yml        # Docker configuration

FastAPI Application Setup

# app/main.py
from fastapi import FastAPI
from app.core.config import settings
from app.api.v1.api import api_router

app = FastAPI(
    title=settings.PROJECT_NAME,
    version=settings.VERSION,
    openapi_url=f"/api/v1/openapi.json"
)

# Include routers
app.include_router(api_router, prefix="/api/v1")

@app.get("/")
async def root():
    return {"message": "Welcome to FastAPI"}

Configuration Management

# app/core/config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "FastAPI App"
    VERSION: str = "1.0.0"
    SECRET_KEY: str
    DATABASE_URL: str
    
    class Config:
        env_file = ".env"

settings = Settings()

FastAPI Best Practices

API Design

• Use Pydantic models for request/response validation
• Implement proper HTTP status codes
• Add comprehensive API documentation
• Use dependency injection for common functionality
• Implement proper error handling

Database Integration

• Use SQLAlchemy with async support
• Implement repository pattern for data access
• Use Alembic for database migrations
• Add proper database connection pooling
• Implement database health checks

Authentication & Security

• Use JWT tokens for authentication
• Implement OAuth2 with scopes
• Add rate limiting for API endpoints
• Use HTTPS in production
• Implement proper CORS configuration

Performance Optimization

• Use async/await for I/O operations
• Implement response caching
• Add database query optimization
• Use connection pooling
• Monitor application performance

Testing Strategy

Test Organization

# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from app.main import app

@pytest.fixture
def client():
    return TestClient(app)

Test Types

• Unit tests for business logic
• Integration tests for API endpoints
• Database tests with test fixtures
• Authentication tests for security

Deployment Considerations

Production Setup

• Use Uvicorn with multiple workers
• Implement proper logging and monitoring
• Set up reverse proxy (Nginx)
• Use environment variables for configuration
• Implement health checks

Docker Configuration

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0"]

Environment Variables

SECRET_KEY=your-secret-key
DATABASE_URL=postgresql://user:pass@host/db
REDIS_URL=redis://localhost:6379

Common FastAPI Patterns

Dependency Injection

from fastapi import Depends
from app.db.database import get_db

@app.get("/users/")
async def get_users(db: Session = Depends(get_db)):
    return users

Background Tasks

from fastapi import BackgroundTasks

@app.post("/send-email/")
async def send_email(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email_task)
    return {"message": "Email sent"}

Middleware

@app.middleware("http")
async def add_process_time_header(request, call_next):
    response = await call_next(request)
    return response

Development Workflow

Getting Started

1. Clone repository
2. Create virtual environment: python -m venv venv
3. Install dependencies: pip install -r requirements.txt
4. Set environment variables
5. Run migrations: alembic upgrade head
6. Start server: uvicorn app.main:app --reload

Code Quality

• Black - Code formatting
• isort - Import sorting
• mypy - Type checking
• pytest - Testing framework
• flake8 - Linting