Developer Requirements Guide

Overview

How we map product requirements to code and tests.

Functional requirements

Product-level requirements: System design → Functional Requirements.

When you implement an endpoint:

• Tie it to at least one stated functional requirement.
• Keep behavior predictable and covered by tests.
• Keep the HTTP contract and database behavior in sync.

Non-functional requirements (NFR)

Non-functional requirements: docs/internal/system-design.html#dev-nfr.

Engineering checklist:

• Performance: avoid N+1 queries and needless serialization work.
• Reliability: use transactions; roll back on failure.
• Maintainability: keep layering strict (api → service → repository).
• Observability: request and business logs are structured and useful for debugging.
• Environments: safe defaults differ by profile (dev / qa / prod).
• Contracts: change APIs and errors in additive ways when possible.
• Idempotent writes: retries must dedupe safely with clear rules.

Requirement-to-implementation mapping

For a new endpoint, check:

1. The requirement is named in the docstring or docs.
2. Request and response schemas are explicit.
3. Business rules live in the service layer.
4. OpenAPI responses document errors.
5. Tests cover success and failure.
6. Write routes document idempotency (Idempotency-Key, replay, conflicts).

Done criteria (requirements)

You are done when:

• Behavior matches the requirement.
• You thought through NFR impact.
• Tests pass.
• Docs are up to date (make docs-fix).

Page history