Backend Engineering Practices¶
Backend engineering standards for the Python/FastAPI/SQLAlchemy codebase.
Architecture Principles¶
- Clean Code: Write testable, maintainable code with clear separation of concerns
- Consistency: Align with existing codebase patterns, libraries, and infrastructure
- Pragmatic Innovation: Only introduce new paradigms if they provide clear value over complexity
- Performance: Optimize for efficiency and scalability
- Resilience: Implement graceful error handling and recovery mechanisms
- Single Responsibility: Each class/module should have one reason to change
- Interface Segregation: Clients should not depend on interfaces they don't use
- Composition over Inheritance: Favor composition and mixins over deep inheritance hierarchies
Code Quality Standards¶
- Testing: Each module must include comprehensive unit tests
- Type Safety: Use type hints and proper interfaces/protocols where applicable
- Error Handling: Comprehensive error scenarios with appropriate logging and recovery
- Documentation: Clear docstrings for all public APIs and complex logic
- Dependencies: Avoid deprecated libraries or functions; verify version compatibility
- Cleanness: Avoid unused imports, unused variables, typing errors, unnecessary logs, and junk code
Development Guidelines¶
- Simplicity: Sometimes less is more — favor simple, testable, clean, and readable code over complex solutions
- Atomic Implementation: Break down features into small, testable subtasks
- Test-Driven Development: Test while implementing — use tests to validate foundations before building upon them
- Separation of Concerns: Maintain clear boundaries between business logic, data access, and external integrations
- Backward Compatibility: Maintain backward compatibility when refactoring existing code
- Document Decisions: Document assumptions and design decisions in code or ADRs
Sections¶
| Guide | Description |
|---|---|
| Design Patterns | ABC/mixins, factory, async-first, layered architecture |
| Dependency Injection | FastAPI Depends(), service chains, parameterized deps |
| Route Patterns | Router organization, response models, query params, uploads |
| Pydantic Schemas | Schema hierarchy, validators, nested relationships |
| Database Patterns | SQLAlchemy async, models, sessions, N+1, Alembic |
| Error Handling | Exception hierarchy, handlers, structured logging |
| Security | JWT, auth dependencies, CORS, rate limiting |
| Performance & Caching | Redis caching, query optimization, parallel I/O |
| Background Tasks | BackgroundTasks, Celery, task queues |
| Configuration | Pydantic Settings, environment management |
| API Design | Versioning, response envelopes, naming conventions |
| Cookbook | Step-by-step recipes for common tasks |
| MediaResource Lifecycle | Content-addressable media management, dedup, canonical paths |
Testing¶
See the dedicated Testing page for full testing strategy, patterns, and best practices.