eryao/backend/AGENTS.md

Backend Domain Rules

This file governs backend/** only. Keep it minimal, enforceable, and non-duplicative.

Scope & Precedence

• Inherits root AGENTS.md and workspace runtime rules.
• If rules conflict, apply the stricter one.
• Keep backend-only constraints here; do not duplicate root routing logic.

Runtime & Commands

• Python commands must use uv (uv run, uv add).
• Backend startup/shutdown must use ./infra/scripts/app.sh.
• Check runtime logs from ./logs/*.log.

Code Quality Baseline

• Do not bypass lint/type gates (ruff, basedpyright).
• Use project logging (core.logging), never print() in runtime code.
• HTTP errors must follow RFC 7807 (application/problem+json).

HTTP Error Contract (Must)

• Backend must construct error payload using RFC7807 fields plus stable extension fields: code and optional params.
• code must be machine-readable UPPER_SNAKE_CASE; do not use free-text detail as the only contract.
• Error code registry source of truth: docs/protocols/common/http-error-codes.md.
• Any create/modify/deprecate of error codes must update docs/protocols/common/http-error-codes.md in the same change.
• Keep response media type as application/problem+json.
• Long-term layering target: HTTP transport details stay in routers/global handlers; service/repository/dependencies should raise domain errors (ApiProblemError or domain-specific exceptions), not HTTPException.
• When refactoring existing code, prefer replacing HTTPException in service/repository/dependencies with ApiProblemError while preserving status/code semantics.

Configuration & Secrets

• Read env only through core.config.settings (Settings / config).
• Do not use os.getenv/manual env parsing in backend runtime.
• Never hardcode keys/tokens/passwords.

Architecture Rules

• Use schema -> repository -> service layering.
• Repository: CRUD + query composition only; no auth decisions, no transaction boundary.
• Service: authz + business logic + transaction boundary.
• owner_id must come from verified JWT (sub), never from client payload.

Schema & Contract Rules

• Schema-first for new/changed data contracts.
• Strong typing required at boundaries (Pydantic/dataclass); avoid weak untyped payload contracts.
• Protocol/data contract changes must stay aligned with docs/protocols/.

Testing

• Follow TDD for feature/bugfix work when practical.
• Prioritize regression tests for changed logic/contracts.
• Real DB tests must use settings.test.*; never hardcode test credentials.