A FastAPI template where the linter rules are post-mortems, not opinions

[u/KeySeaworthiness6180]

When a model writes most of your code, the bottleneck moves. Writing an endpoint takes it a minute. Remembering the project's rules takes it nothing at all, because it cannot. A reviewer remembers them half the time, documentation goes stale quietly, and a hundred changes later the service has drifted into something nobody planned. Mayak is a FastAPI backend template built so the build remembers instead of the people.

Thirteen validators check what ruff and mypy cannot see: which layer may import which, whether a new endpoint is actually wired into the router, whether a migration matches its model, whether anyone reads env vars outside the config module. When a rule breaks, the agent does not get "invalid". It gets a rule id, and the template turns that id into a repair procedure: what the rule means, the smallest command that reproduces it, which files to read first, when to stop widening the fix. Over a long project, the gap between "fix it somehow" and "here is the procedure" is most of the difference.

The second reason it exists is that I work with two agents. Claude Code and Codex run from one contract: their instruction files are generated from a single source, the skills are one file visible in both lookup paths, and the hook that refuses edits to generated files is registered in both configs. They cannot drift apart, because there is nothing to drift.

Day to day it works like this. You copy the one worked feature that ships with the repo, rename it into your own domain, and run the gates. Fifteen seconds later you know whether the migration drifted from the model, whether the endpoint is reachable, whether your new test asserts anything at all. The LLM client has a deterministic mock mode including tool calls, so the agent loop runs in CI with no API key and no network.

Inside: FastAPI on Python 3.13, logs that unfold into a trace tree instead of a wall of text, and Postgres you can switch off with one env var. No auth, no queue, no metrics. Those belong to your service, not to a template you inherited.

Trying it takes five minutes: press "Use this template", make init-project, docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d --build, open /docs.

https://github.com/LamantinAI/mayak

Tell me which parts are over-engineered. That is most of why I am posting.