Python Backend Development Standards

Architecture Overview

Router/Controller → Service → Repository → Database
      ↓                ↓            ↓
   Schemas         Business      SQLAlchemy
  (Pydantic)        Logic         Models

Layer Responsibilities

| Layer | Location | Purpose | |-------|----------|---------| | Models | app/models/ | SQLAlchemy ORM, database schema | | Schemas | app/schemas/ | Pydantic DTOs (request/response) | | Repositories | app/repositories/ | Database CRUD operations | | Services | app/services/ | Business logic orchestration | | Controllers | app/api/v1/ | FastAPI routes, thin handlers | | Migrations | alembic/versions/ | Database migrations |

Naming Conventions

Files

All lowercase with underscores: user_profile.py
One entity per file
Match filename to class: user.py → class User

Classes

Models: User, BlogPost (PascalCase, singular)
Schemas: UserCreate, UserResponse, UserUpdate
Repositories: UserRepository
Services: UserService

Database

Table names: plural snake_case (users, blog_posts)
Column names: snake_case (created_at, user_id)

Alembic Migrations

File Naming Convention

yyyymmdd_HHmm_<feature>.py

Examples:

20260117_0930_create_users_table.py
20260117_1045_add_email_to_users.py
20260117_1400_create_api_keys_table.py

Create Migration Command

# Generate with autogenerate
alembic revision --autogenerate -m "description"

# Then rename the file to follow convention:
# FROM: xxxx_description.py
# TO:   yyyymmdd_HHmm_description.py

Code Standards

Async Everything

All database operations must be async
Use async def for all handlers, services, repositories
Use await for all I/O operations

Dependency Injection

Use FastAPI Depends() for dependencies
Inject database sessions into services
Services inject repositories

Error Handling

Use custom exceptions in app/core/exceptions.py
Let FastAPI exception handlers convert to HTTP responses
Never catch and swallow exceptions silently

Security

Argon2id for password hashing
Parameterized queries (SQLAlchemy ORM)
Input validation (Pydantic)
Rate limiting on auth endpoints

Reference Navigation

Core Patterns:

python-models.md - SQLAlchemy ORM (User, ApiKey)
python-schemas.md - Pydantic v2 patterns
python-repositories.md - Repository pattern
python-services.md - Service layer patterns
python-api-design.md - FastAPI routes and controllers
python-migrations.md - Alembic migration patterns
python-utils.md - Utility functions (datetime, string, validation)

Security & Auth:

python-authentication.md - JWT, API Keys, OAuth
python-middleware.md - Dual auth, rate limiting, credits
python-security.md - OWASP Top 10, input validation

Quality & Operations:

python-testing.md - pytest patterns, fixtures
python-performance.md - Caching, query optimization, async
python-debugging.md - Logging, profiling, error tracking
python-devops.md - Docker, CI/CD, deployment