# Build Recipe

## Summary

Follow this ordered checklist to generate a new application of the standard
shape. Every step is deterministic; only steps 2 and 7 require app-specific
authoring.

---

## 0. Query the registry

Before writing anything, read the **library registry** and note which internal
libraries provide DB, DI, routing, ingestion, auth, and docs. Do not
reimplement them.

## 1. Scaffold the repository

Copy the `templates/` skeleton. It provides: `pyproject.toml`, `openapi.yaml`,
`main.py`, `init.py`, `worker.py`, `config.py`, `Dockerfile`,
`docker-compose.yaml`, `.env.example`, and the package tree
(`domain/ infra/ interfaces/ pipelines/ tests/ scripts/`).

## 2. Author the spec  *(app-specific)*

Write `openapi.yaml`: resources, schemas, `operationId`s, security, and any
extension metadata. This is the contract.

## 3. Write each CRUD slice  *(app-specific)*

For each resource, create the four-file slice (see **CRUD Template**):
`models.py`, `ports/db.py`, `ports/service.py`, optional `converters.py`.

## 4. Wire the composition root

In `init.py`: build leaf repositories, then dependent repositories, then
services; add infrastructure adaptors (cache store, progress bus, stores,
fetchers). Add `get_svc` overloads.

## 5. Add routes

Create `interfaces/<resource>/routes.py` (thin handlers) and re-export them in
`interfaces/openapi.py`. Add a cache decorator to read endpoints.

## 6. Bootstrap the app and worker

Confirm `main.py` wires the OpenAPI-first app with the lifespan. If the app has
long-running jobs, adapt `worker.py` to poll the relevant job collection.

## 7. Add a pipeline family  *(only if data-driven)*

Create `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,
`resources/`, and register the root in `registry.py`. Add fixtures and a parity
test.

## 8. Add infrastructure as needed

Only where the standard adaptors do not cover the need. Prefer library-backed
adapters.

## 9. Tests

Add integration tests with fakes and unit tests for domain/pipeline logic; add
a config-consistency test if using rule-driven pipelines.

## 10. Scripts and seeds

Add operator scripts under `scripts/` that use `init()` / `get_svc()` /
`shutdown()`.

## 11. Docs

Author GSDFC docstrings, generate the type stubs (`.pyi`), mark the package
`py.typed`, and build docs.

## Definition of done

- `python -c "import main"` succeeds.
- `pytest` passes.
- The app serves the spec's operations; the worker drains its queue.
- No domain module imports a web framework.
- No infrastructure was reimplemented that a library already provides.