docs(standards): move build recipe into the MCP bundle; add Start an App entry point
This commit is contained in:
150
standards/src/lib/01_build_recipe.md
Normal file
150
standards/src/lib/01_build_recipe.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# 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) and the
|
||||
pipeline family (step 7) need app-specific authoring.
|
||||
|
||||
This page is served by the `standards` MCP as `doc://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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
````markdown
|
||||
# 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 and 3 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:
|
||||
- `doc://nav` (the module list)
|
||||
- `doc://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)
|
||||
- `doc://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>/`.
|
||||
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.
|
||||
|
||||
3. **Write each CRUD slice (app-specific)** — per resource create the four-file
|
||||
slice: `models.py`, `ports/db.py`, `ports/service.py`, and optional
|
||||
`converters.py`. Follow the CRUD template.
|
||||
|
||||
4. **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.
|
||||
|
||||
5. **Add routes** — create `interfaces/<resource>/routes.py` thin handlers bound
|
||||
to `operationId`s and re-export them in `interfaces/openapi.py`. Add the cache
|
||||
decorator to read endpoints.
|
||||
|
||||
6. **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.
|
||||
|
||||
7. **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.
|
||||
|
||||
8. **Add infrastructure only where needed** — Tier A capability: use the
|
||||
library. Tier B capability: copy the template. Never hand-write a Tier A
|
||||
library.
|
||||
|
||||
9. **Tests** — integration tests with fakes at the HTTP edge; unit tests for
|
||||
domain and pipeline logic; a config-consistency test for rule-driven
|
||||
pipelines.
|
||||
|
||||
10. **Scripts and seeds** — operator scripts under `scripts/` using
|
||||
`init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.<name>`.
|
||||
|
||||
11. **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 · CRUD slices | `domain/<resource>/` | spec, CRUD template |
|
||||
| 4 · Wiring | `init.py` | every slice |
|
||||
| 5 · Routes | `interfaces/<resource>/` | services, openapi route registry |
|
||||
| 6 · Bootstrap | `main.py`, `worker.py` | composition root |
|
||||
| 7 · Pipelines | `pipelines/<family>/`, `shared/` | library pipeline engine |
|
||||
| 8 · Infra | `infra/` | domain ports |
|
||||
| 9 · Tests | `tests/` | app + fixtures |
|
||||
| 10 · Scripts | `scripts/` | composition root |
|
||||
| 11 · Docs | docstrings + docs build | code, Doc Forge |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 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.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [02 – Layering Rules](02_layering_rules.md) · [05 – CRUD Template](05_crud_template.md) · [06 – Pipeline Scaffold](06_pipeline_scaffold.md) · [12 – Genericity Matrix](12_genericity_matrix.md)
|
||||
@@ -3,6 +3,7 @@
|
||||
The reference half of the Standards description: the enforceable rules,
|
||||
patterns, and the internal library catalog that agents consult while coding.
|
||||
|
||||
- **Build Recipe** — the ordered, agentic checklist for a new app.
|
||||
- **Layering Rules** — the strict request → domain → repository layering and
|
||||
the rules that enforce it.
|
||||
- **Composition Root** — a single composition point wiring the whole app.
|
||||
|
||||
Reference in New Issue
Block a user