AGENTS.md — FastAPI service

An async Python API where Pydantic models define every request and response, and the OpenAPI document is generated from the code.

Setup and commands

• dev: uv run fastapi dev app/main.py
• lint: uv run ruff check . && uv run ruff format --check . && uv run mypy app
• test: uv run pytest
• build: docker build -t service .
• deploy: uv run alembic upgrade head && docker push service
• install: uv sync

Project structure

• app/main.py — Creates the FastAPI app, includes routers, sets lifespan for pools
• app/api/ — One router module per resource; thin handlers only
• app/schemas/ — Pydantic request and response models
• app/services/ — Business logic, taking a session and plain arguments
• app/db/ — SQLAlchemy models, session factory and Alembic migrations
• app/core/ — Settings (pydantic-settings), security, logging
• tests/ — Unit tests for services and API tests per router

Code style

• Files: snake_case.py
• Tests: tests/test_<module>.py; tests/api/test_<router>.py
• Branches: type/short-description, e.g. feat/scoring-endpoint

Code

• Prefer small, pure functions and explicit types at module boundaries. (Easier to test, review and change.)
• Inject the database session, settings and current user with Depends; never import a global session. (Tests swap dependencies with app.dependency_overrides.)

Components

• Components read design tokens; no raw hex values, pixel sizes or font names in component code. (One token change restyles the product.)

Data

• Analytics events are object_action in snake_case and come from the experience skill’s measures. (Names stay consistent across teams and tools.)
• Separate input and output models (OrderCreate, OrderRead) and always set response_model on routes. (Output models stop internal fields such as password hashes from leaking.)

Errors

• Every async action has loading, empty, error and success states, matching the experience skill. (Unhandled states are where users get stuck.)
• Raise HTTPException only in the API layer; services raise domain exceptions mapped by exception handlers to problem+json. (Services stay reusable from workers and scripts.)

Security

• Secrets never live in the repository; read them from the environment or a secret store. (A leaked key outlives the commit that removed it.)
• Validate every input on the server, even when the client already did. (Clients can be bypassed.)
• Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. (Cheap protection against the most common attacks.)
• Resolve the current user in a dependency and scope every query by it; reject requests whose path id the user does not own. (Object-level authorisation is the top API risk.)

Performance

• Never call blocking libraries inside async def handlers; use def handlers or run_in_threadpool for sync code. (One blocking call stalls every request on that worker.)
• Open the engine and HTTP clients once in the lifespan handler and set pool size and timeouts explicitly. (Per-request connections exhaust the database under load.)

Accessibility

• Use native elements first; add ARIA only when no native element fits. (Native controls bring keyboard and screen-reader support for free.)

Design and journeys

This stack has no UI; design skills do not apply.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events object_action from its measures.

Testing and checks (must pass before a pull request)

Pull requests

• Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

Review checklist

• Correctness: does it do what the issue asks, including edge cases?
• Readability: could a new teammate change it safely?
• Architecture: is it in the right place, with the right boundaries?
• Security: inputs, secrets, permissions, dependencies
• Performance: budgets, queries, bundle size
• Tests fail when the code is broken (flip a condition and re-run)
• One approving review; two for auth, migrations or data deletion
• Reviewer checks the openapi.json diff first

Definition of done

• Acceptance criteria met and demoed on the preview link
• Tests added for new behaviour and every state
• Accessibility and performance gates green
• Analytics events named from the experience skill
• Docs or changelog updated when behaviour changes
• Request and response models for every route
• API test covers success, 422 validation and 403 ownership cases

Release

• Small pull requests (aim for under 400 changed lines)
• CI green before review
• Squash-merge to main; main is always deployable
• Every release has a written rollback path
• Alembic migration runs as a release step, then a rolling update
• Migrations are additive; column drops ship one release later

Incidents

• Roll back by redeploying the previous image tag
• Blameless note within 48 hours

Generated from the Celestial engineering skill “FastAPI service” (engineering core v1.0, checked 2026-10-26).