docs/standards_src/wiki/11_build_recipe.md

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, operationIds, 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.