Python Backend Fastapi

Standard implementation workflow

1) Context discovery (do not invent patterns)

• Locate existing routers, dependency injection conventions, error handling, and response schema patterns.
• Identify service layer boundaries (or create them if missing).
• Find existing migration conventions and logging format.

2) API contract first (Pydantic v2)

• Define/extend request & response models with Pydantic v2.
• Ensure OpenAPI reflects reality (status codes, response shapes, optional fields).
• Keep handlers thin: parse/validate, delegate to service, map service result to response.

Definition of “thin handler”:

• No business rules in the endpoint function beyond wiring + basic validation.
• No direct DB logic in the handler unless the codebase already standardizes it there.

3) Service layer + tests (pytest)

• Move business logic to a service module with unit tests.
• Prefer tests that encode behavior and edge cases (happy path, validation, not found, conflicts).
• Add/extend fixtures in line with repo conventions.

4) Dependency Injection (FastAPI Depends)

• Use Depends for DI and request-scoped dependencies.
• If a request-id is used in the project, propagate it through dependencies/services.

5) Alembic migrations (every schema change)

• Create a new revision for each schema change.
• Make migrations idempotent and safe:
  • avoid non-deterministic operations
  • provide both upgrade and downgrade
  • ensure ordering is correct with dependencies
• If the change is data-destructive, clearly annotate risk and required operator steps.

6) Logging (stdlib logging)

• Use Python stdlib logging.
• Include request id (if available) and key fields relevant to the operation.
• Avoid logging secrets/PII; log identifiers and high-level state transitions instead.

7) ETL / parsers (streaming, error CSV)

When implementing ingestion/parsing:

• Process input file-by-file (and ideally row-by-row) to avoid loading all data into memory.
• For invalid records:
  • write a CSV containing: timestamp, file, line, error, original_row
  • keep original_row as close to raw input as possible (avoid “fixing” it before logging)
• Logging must allow operators to reproduce and patch upstream data.

Definition of done (backend changes)

A change is “done” only if:

1. endpoint behavior matches contract (schemas + status codes)
2. tests exist and pass for new/changed logic
3. migrations exist for schema changes (upgrade + downgrade)
4. logging is present for operationally relevant paths
5. for new endpoints: provide example curl or httpie calls + expected responses

Examples (template snippets)

Example: endpoint acceptance checklist

• Request model defined (Pydantic v2)
• Response model defined (Pydantic v2)
• Handler delegates to service
• Tests cover core behavior + edge case
• Example curl included in PR/plan notes

Example: ETL error row

• timestamp: ISO-8601
• file: input filename
• line: input line number (1-based)
• error: short human-readable description
• original_row: raw row payload