Skip to content

Build Recipe

Summary

The ordered, deterministic checklist for generating a new application of the standard shape. Every step is fixed; only the resource model (step 2), the codegen pass (step 3), and the pipeline family (step 8) need app-specific work.

This page is served by the standards MCP as docs://modules/build_recipe. The start_app prompt on that server collects the two axes and hands off here; pull exact files with get_app_component.

🚀 Bootstrap

From the standards docs checkout:

1
2
cp -r <docs>/standards/src/templates/app apps/<your-app>
cd apps/<your-app>

Install the internal libraries — editable local checkouts (preferred in development) or the private index (CI / fresh machines). Credentials are environment-only; never commit them.

1
2
3
4
5
6
# local checkouts
pip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa \
            -e ../aetos/dagpipe -e ../aetos/doc-forge
# private index
pip install --extra-index-url \
  "https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple" .

📋 Agent prompt (copyable)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
# Build a new application from the Aetos Standards blueprint

You are coding a complete new backend application conforming to the Aetos
standard app blueprint. Execute every step in order. Only steps 2–4 use the
app-specific details provided by the user; everything else is deterministic.

## Before writing any code

Connect to the `standards` MCP server and read:
- `docs://nav` (the module list)
- `docs://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)
- `docs://modules/layering_rules` (the dependency rules)

Then:
- call `find_library` with `db`, `di`, `routing`, `ingestion`, `pipeline`, `docs`
  and note the Tier A libraries that already exist — never reimplement one;
- call `list_app_components()` and pull each file you need with
  `get_app_component(kind, resource=..., family=...)` instead of writing it from
  scratch.

## Steps

1. **Scaffold** — copy `standards/src/templates/app/` into `apps/<your-app>/`
   (or pull the same tree via `get_app_template`). Keep the tree: `domain/`,
   `infra/`, `interfaces/`, `pipelines/`, `tests/`, `scripts/`, plus
   `pyproject.toml`, `openapi.yaml`, `config.py`, `init.py`, `main.py`,
   `worker.py`, `Dockerfile`, `docker-compose.yaml`, `.env.example`.

2. **Author the spec (app-specific)** — write `openapi.yaml`: resources,
   schemas, `operationId`s, security, and extension metadata. This is the
   contract and drives all routing. Every operation MUST have an `operationId`.

3. **Generate the scaffold (codegen)** — from the spec, generate the wire
   models and the exact handler signatures:
   ```bash
   openapi-first models openapi.yaml -o _gen/models.py
   openapi-first routes openapi.yaml -o _gen/routes \
     --use-models --models-module _gen.models --inject-request --package
   ```
   `_gen/models.py` is the **wire contract** (Pydantic, one class per
   `components.schemas` entry). `_gen/routes/<resource>/routes.py` lists every
   `operationId` with its exact parameter signature. Treat `_gen/` as generated
   (never hand-edit it) — the canonical handlers live in `interfaces/`.

4. **Write each CRUD slice (app-specific)** — per resource create the four-file
   slice: `models.py` (domain model, **no `id`**), `ports/db.py`
   (`class XDocument(BaseDocument, X)` — id comes from `BaseDocument`),
   `ports/service.py`, and optional `converters.py`. Follow the CRUD template.

5. **Wire the composition root** — in `init.py`, build leaf repositories, then
   dependent repositories, then services; add infra adapters (db, cache, stores,
   progress bus, fetchers). Expose `get_svc` overloads.

6. **Add routes** — create `interfaces/<resource>/routes.py` thin handlers whose
   names match the `operationId`s (use the signatures from step 3 as your
   checklist) and re-export them in `interfaces/openapi.py`. Add the cache
   decorator to read endpoints.

7. **Bootstrap app and worker** — confirm `main.py` runs the OpenAPI-first app
   with its lifespan. If the app has long-running jobs, adapt `worker.py` to poll
   the job collection, run the pipeline, and publish progress.

8. **Add pipeline families (only if data-driven)** — copy `pipelines/example/`
   to `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,
   `resources/`, and reuse `pipelines/shared/` (loader + registry). Register the
   root. Add fixtures and a parity test.

9. **Add infrastructure only where needed** — Tier A capability: use the
   library. Tier B capability: copy the template. Never hand-write a Tier A
   library.

10. **Tests** — integration tests with fakes at the HTTP edge; unit tests for
    domain and pipeline logic; a config-consistency test for rule-driven
    pipelines. Include `tests/integration/test_openapi_app_builds.py` (imports
    the app, asserts `import main` binds every operation).

11. **Scripts and seeds** — operator scripts under `scripts/` using
    `init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.<name>`.

12. **Docs** — author GSDFC docstrings, generate `.pyi` stubs, mark the package
    `py.typed`, and build the docs.

**Definition of done:**
- `python -c "import main"` succeeds.
- `pytest` passes.
- The app serves every operation in the spec; the worker drains its queue.
- No domain module imports a web framework.
- No Tier A library was reimplemented.

🧭 Where the steps land

The steps map onto the layers as follows:

Step Package / file Depends on
1 · Scaffold whole templates/app/ —
2 · Spec openapi.yaml —
3 · Codegen _gen/ (generated) spec, openapi-first
4 · CRUD slices domain/<resource>/ spec, CRUD template
5 · Wiring init.py every slice
6 · Routes interfaces/<resource>/ services, openapi route registry
7 · Bootstrap main.py, worker.py composition root
8 · Pipelines pipelines/<family>/, shared/ library pipeline engine
9 · Infra infra/ domain ports
10 · Tests tests/ app + fixtures
11 · Scripts scripts/ composition root
12 · Docs docstrings + docs build code, Doc Forge

🔧 The codegen fast path, in detail

openapi-first is spec → code only (it never generates a spec). Use it to erase the two mechanical parts of the build:

Generated artifact Replaces Notes
_gen/models.py hand-writing Pydantic wire models one class per components.schemas entry
_gen/routes/<resource>/routes.py hand-typing handler signatures names == operationIds; request: Request injected

Rules of the road:

  • Wire models are not domain models. _gen/models.py is the HTTP contract; domain/<resource>/models.py is your business shape. If the spec's schema has a required id: str, keep it off the domain model and let the document get its id from BaseDocument.
  • Resource names are sanitized. /fetch-requests → fetch_requests.py.
  • Multipart bodies expand to UploadFile = File(...) / Form(...) params.
  • _gen/ is disposable. Regenerate on every spec change; git diff shows exactly what moved.

⚠️ 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 Tier A library was reimplemented.