A practical backend development standard for our engineering club.
This repository defines the engineering standards, development practices, architecture rules, and code-quality expectations that backend developers in the club should follow when building and maintaining backend systems.
The goal is simple:
Build backends that are understandable, secure, testable, maintainable, and ready to grow.
This is not a collection of theoretical programming rules. Every important guideline should be supported by practical examples showing:
- ❌ Bad — what should not be done
- ✅ Good — the recommended approach
- Why? — why the recommended approach is better
Our backend projects primarily use:
- Python
- FastAPI
- PostgreSQL
- SQLAlchemy
- Alembic
- Pydantic
- JWT / OAuth2 where appropriate
- Docker / Docker Compose
- Redis where required
- Pytest
- Git & GitHub
- GitHub Actions
- Object storage for uploaded files when required
Projects may use additional technologies when there is a valid technical reason, but introducing a technology should be intentional rather than unnecessary.
How backend projects should be structured and how responsibilities should be separated.
Topics include:
- Project/folder structure
- Route/controller responsibilities
- Service layer
- Repository/data-access layer
- Models
- Schemas
- Dependency injection
- Separation of concerns
See architecture.md.
Standards for designing consistent APIs.
Topics include:
- Endpoint naming
- HTTP methods
- Request schemas
- Response schemas
- HTTP status codes
- Validation
- Pagination
- Filtering
- Sorting
- API versioning
- API documentation
See api-guidelines.md.
Standards for designing and interacting with PostgreSQL databases.
Topics include:
- Database/model design
- Relationships
- Constraints
- Indexes
- Foreign keys
- Transactions
- Query optimization
- SQLAlchemy usage
- Alembic migrations
- N+1 query prevention
Standards for protecting backend resources.
Topics include:
- Authentication
- Password handling
- JWT
- OAuth2
- Role-based access control
- Permissions
- Token handling
- Protected endpoints
- Authentication dependencies
See authentication.md.
Standards for handling failures consistently.
Topics include:
- HTTP exceptions
- Custom exceptions
- Error responses
- Validation errors
- Database errors
- Logging errors
- Avoiding leaked internal information
See error-handling.md.
Security requirements for backend applications.
Topics include:
- Secrets
- Environment variables
- Password security
- Authentication
- Authorization
- Input validation
- SQL injection
- File-upload security
- CORS
- Rate limiting
- Sensitive information
- Dependency security
See security.md.
Standards for proving that backend code works.
Topics include:
- Unit tests
- Integration tests
- API tests
- Database tests
- Authentication tests
- Error tests
- Fixtures
- Test organization
- CI testing
See testing.md.
Standards for working together safely.
Topics include:
- Branching
- Commit messages
- Pull requests
- Code review
- Merge strategy
- Protected branches
- Resolving conflicts
- Avoiding direct pushes to production branches
See git-workflow.md.
Standards reviewers should use when evaluating backend code.
A backend should not be considered complete simply because:
"The endpoint works."
Reviewers should evaluate:
- Architecture
- Correctness
- Security
- Database design
- API design
- Validation
- Error handling
- Testing
- Performance
- Maintainability
- Documentation
See code-review.md.
Practical guidelines for keeping backends fast under real load.
Topics include:
- Database indexes and query optimization
- N+1 query prevention
- Pagination
- Connection pooling
- Redis caching (when and when not to use it)
- Async vs sync usage
- Background jobs
- Response payload size
See performance.md.
A backend feature is not complete merely because it works locally.
A feature should generally satisfy the following:
Feature
│
├── Correct architecture
├── Request validation
├── Authorization
├── Proper error handling
├── Correct HTTP status codes
├── Database changes + migration
├── Tests
├── Documentation
├── Security review
├── Performance considerations
├── Code review
└── CI checks passing
The exact requirements may depend on the feature.
A backend is maintained by people, not by the computer that executes it.
Prefer:
clear
predictable
consistent
testable
maintainable
over:
clever
complicated
duplicated
tightly coupled
difficult to test
The examples/ directory contains deliberately bad and good implementations.
These examples exist to demonstrate the difference between code that merely works and code that follows engineering standards.
examples/
├── bad-example/
└── good-example/
When possible, examples should show:
# Problematic implementation# Recommended implementationExplain the engineering reason for the difference.
When starting a new backend project:
- Read the architecture guidelines.
- Follow the API guidelines.
- Follow the database guidelines.
- Implement authentication and authorization correctly.
- Follow the security requirements.
- Write tests.
- Follow the Git workflow.
- Open a pull request.
- Have the code reviewed.
- Fix review findings before merging.
When reviewing an existing backend:
- Identify violations of these standards.
- Prioritize security and correctness problems.
- Identify architectural problems.
- Identify maintainability problems.
- Create issues for larger refactoring work.
- Do not blindly rewrite everything.
- Improve the system incrementally.
Not every existing project will immediately comply with every standard.
Do not rewrite an entire backend just because it contains technical debt.
Instead:
Identify
↓
Prioritize
↓
Document
↓
Fix
↓
Test
↓
Review
↓
Prevent regression
Critical security or correctness problems should be addressed first.
The purpose of these standards is not to make developers write more code.
The purpose is to make developers write better code.
A good backend should be:
Correct + Secure + Maintainable + Testable + Understandable + Scalable
These standards are living documentation.
As the club gains experience, discovers better practices, or adopts new technologies, this repository should evolve.
Changes to the standards should themselves go through review.
Backend Engineering Team
Repository: backend-engineering-standards
Purpose: Establish consistent backend engineering practices across the club.