Skip to content

imperfect-api

FastAPI backend for the Imperfect health and fitness application.

This documentation is written for two readers at once: humans onboarding to the service, and coding agents that need durable context without expanding the always-loaded AGENTS.md file. The short rule is:

  • AGENTS.md is the terse map: commands, conventions, module routing, and high-level contracts.
  • docs/*.md holds cross-cutting system context, API contracts, harnesses, and launch gates.
  • Module CLAUDE.md files describe complex local subsystems.
  • Source docstrings hold module-local retrospective rationale and invariants.

Start Here

  • API reference - route families, generated OpenAPI, and Redoc.
  • Architecture - service boundaries, data flows, and design decisions that span modules.
  • Learnings - durable issue and PR takeaways that should change future decisions.
  • Public route contract - browser route API, share, locale, progress, and font contract.
  • Telemetry smoke - hermetic telemetry validation commands and Logfire queries.

Local Docs

Build the site:

make docs

Serve it locally:

make docs-serve

The site is configured for https://imperfect-api.imperfect.sh. It becomes available there after the GitHub Pages workflow deploys from main and DNS points the host at GitHub Pages.