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