Contributing

Development Setup

1. Clone and configure

git clone <repo>
cd cms-api
cp .env.example .env

2. Start services

docker compose up -d

3. Apply migrations and seed

docker compose exec api alembic upgrade head
docker compose exec api python -m app.core.seed

4. Verify

http://localhost:8100/docs   → Swagger UI
http://localhost:8200        → Documentation

Code Style

Layered architecture — respect the layer boundaries:

Layer	Allowed to call	Not allowed to call
Router	Service, Schema	Repository, Model
Service	Repository	Router
Repository	Model	Service, Router

Naming conventions

Files: snake_case.py
Classes: PascalCase
Constants: UPPER_CASE
Private methods: _leading_underscore

Schemas — always use dedicated schemas per operation:

UserCreate    # POST — input
UserUpdate    # PATCH — input (all fields optional)
UserResponse  # output — never expose password_hash
UserSummary   # list output — compact version

Adding a New Resource

Follow this checklist when adding a new resource to the API:

□ Migration       — new table in migrations/versions/
□ Model           — app/models/your_model.py
□ Schema          — app/schemas/your_schema.py (Create, Update, Response, Summary)
□ Repository      — app/repositories/your_repository.py
□ Service         — app/services/your_service.py
□ Router          — app/api/v1/your_router.py
□ Register router — app/api/v1/router.py
□ Permissions     — add to seed.py and assign to appropriate roles
□ Documentation   — docs/api/your_resource.md

Environment Variables

Never hardcode configuration values. Always use settings from app.core.config:

from app.core.config import settings

# Good
expire = settings.ACCESS_TOKEN_EXPIRE_MINUTES

# Bad
expire = 15

Git Workflow

main        — stable, production-ready
develop     — integration branch
feature/*   — new features
fix/*       — bug fixes

Commit message format:

feat: add password reset endpoint
fix: correct token expiry calculation
docs: update RBAC documentation
refactor: extract token generation to helper