Reference Service¶
The PyFr reference service.
This site documents the service: how to run it (Getting started), what to do when it misbehaves (Runbook), how to change it (Guides), what it exposes (Reference), and why it is built the way it is (Decisions, Explanation).
The service was generated from PyFr, a cookiecutter template for production-ready Python microservices; PyFr's own site describes the template.
What you get¶
Everything below runs today, and every item has a page:
- An HTTP API with an application factory and a lifespan, interactive
documentation at
/docs, and RFC 9457 Problem Details for every error — RFC 9457 is the internet standard shape for a JSON error body. The endpoints are in HTTP API; the committed OpenAPI document and its drift gate in The API contract. - Four layers — domain, services, infrastructure, api — with the dependency rule enforced by a build check, not by code review. Architecture is the overview.
- Configuration validated at startup. A bad value stops the process with a readable message instead of causing an error an hour later. Every variable is in Configuration.
- Structured logging — one JSON object per line on standard output, with correlation identifiers and redaction — in Logging.
- OpenTelemetry traces, metrics and logs, a local Grafana stack, three dashboards and service level objective alerts — in Observability.
- Three health endpoints answering three different questions, with
readiness in two tiers: a required dependency gates
/readyz, an optional one is reported without gating. HTTP API has the shape; Observability has the reasoning. - Graceful shutdown, so a rolling deployment does not drop live requests — and the deadline trap to avoid, in Run in a container.
- Two hardened container images — the service, and a migrations image
that applies the schema before the service starts — non-root, no build
tools, no shell utilities in the final layer, built for
amd64andarm64, scanned before every release. Run in a container and Supply chain. - Its own workflows, running from the first push:
ci.yml,nightly.yml,release.yml,docs.ymlandtemplate-update.yml, with a Dependabot schedule. Contributing has the checks they run; Supply chain the security ones; theREADME.md's Continuous integration and releases section lists all five and the repository settings they need. - An outbound HTTP client with retries and a circuit breaker, and recorded cassettes for its tests — in Outbound HTTP calls.
Where to go next¶
| If you want to | Read |
|---|---|
| Run the service and place an order | Getting started |
| Fix it at three in the morning | Runbook |
| Add your own endpoint through all four layers | Add an endpoint |
| Store data in something the service does not ship | Add a backend |
Look up a just command |
Commands |
| Look up an environment variable | Configuration |
| Look up an endpoint or an error shape | HTTP API · Errors |
| Understand how the pieces fit | Architecture |
| Work on the service | Contributing |
| Look up a term used on this site | Glossary |