docs/standards/src/templates

Application Template

A minimal, runnable skeleton of the standardized architecture. It demonstrates both axes of the blueprint (see standards):

1. Resource axis — items and jobs, each a Claude-style generic CRUD slice (model → document → repo → service → route), all driven from openapi.yaml.
2. Pipeline axis — a background worker.py that polls pending jobs and runs a pipeline; pipelines/example/ shows the reusable family skeleton and pipelines/item_sync.py the simple end-to-end form.

Everything here is deliberately small so an agent can rewrite each file rather than delete unused code. The domain is a neutral "item", not an app noun.

Internal dependencies

The app depends on the internal Aetos libraries (openapi-first, mongo-ops, hexa, dagpipe, doc-forge). Install them one of two ways.

• Local checkouts (preferred in development) — install the sibling repos editable:

  pip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa `
              -e ../aetos/dagpipe -e ../aetos/doc-forge
  

• Private index (CI / fresh machines) — the published wheels live on the Aetos index. Pass credentials through the environment only; never commit them:

  pip install --extra-index-url `
    "https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple" .
  

  The Dockerfile reads PIP_REGISTRY_USERNAME / PIP_REGISTRY_PASSWORD as build args and sets PIP_EXTRA_INDEX_URL accordingly.

Instantiate a new app

cp -r src/templates/app apps/<your-app>
cd apps/<your-app>

1. pyproject.toml — rename the package; keep the internal library pins.
2. config.py — replace/add settings consumed by your domain.
3. openapi.yaml — replace the Item/Job resources with your resources.
4. domain/ — rename item and job slices to your aggregates.
5. pipelines/ — replace the demo with your pipeline (see below).
6. tests/ — keep the two test files as the pattern for your own.

Install and run:

pip install -e ".[dev]"
uvicorn main:app --reload     # API
python worker.py              # worker
python -m scripts.seed        # operator script

Pipeline families

pipelines/item_sync.py is the smallest possible pipeline (plain async steps). When a family needs its own stages, copy pipelines/example/:

pipelines/<family>/
    abc.py            # port contracts
    impl.py           # concrete stages + wired root + register(...)
    pipeline.yaml     # graph spec
    resources/
        pipeline.yaml # runtime spec
        patterns/*.yaml
pipelines/shared/
    ports.py loader.py registry.py   # reused by every family

The shared loader wires the root through the DI library (hexa.build) and merges the pattern fragments; the registry resolves a (kind, variant, mode) triple to a root class. See standards "50_pipeline_scaffold".

What to keep, what to replace

Keep	Replace / rename
config.py shape	Settings fields
init.py wiring pattern	Resource names
openapi-first routing	Paths, schemas, operationIds
mongo-ops repo factory	Collections, doc models
generic CRUD adaptor	Nothing (reuse as-is)
pipelines/shared/	Nothing (reuse as-is)
pipelines/example/	Family name, stages, patterns
worker poll + status loop	Job payloads, pipeline steps
scripts/	Task bodies

Where the internal libraries slot in

• openapi_first.app.OpenAPIFirstApp — main.py, interfaces/openapi.py
• mongo_ops — infra/db/setup.py, infra/db/repos/mongo.py, domain/*/ports/db.py
• hexa.build — domain/*/ports/service.py, pipelines/shared/loader.py
• dagpipe — pipelines/ (wrap step chains in a DAG once they branch)
• docforge — generated .pyi stubs and docs
• omniread / mail-intake — ingestion adapters (add when needed)

Confirm current endpoints and ownership with the standards registry MCP tools: find_library("pipeline"), find_library("auth"), or get_app_component("pipeline-abc", family="csv").