83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
# 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.
|