# Application Template

A runnable sample of the standardized architecture — the **vet** veterinary
clinic domain, kept as the standards' reference sample. It demonstrates both
axes of the blueprint (see `standards`):

1. **Resource axis** — five domain aggregates (parents, pets, treatments,
   vets, appointments) plus a **jobs** queue, each a CRUD slice
   (model → document → repo → service → route), all driven from
   `openapi.yaml`. x- extension fields on the spec drive the admin client.
2. **Pipeline axis** — a background `worker.py` that polls pending jobs and
   dispatches by `job.kind`; `pipelines/appointment_reminder/` is the worked
   family and `pipelines/shared/` the reusable scaffold.

Copy a slice, replace the domain with your own — the layer structure, wiring
patterns and tests stay.

## 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 (keep the
   worker knobs if you run jobs).
3. `openapi.yaml` — replace the vet resources with yours; keep the x-
   extension conventions on schemas and fields.
4. `domain/` — replace each aggregate slice with your own; copy
   `domain/parents/` as the simplest pattern, `domain/appointments/` when you
   need FK expansion.
5. `interfaces/` — one `routes.py` per resource re-exported from
   `openapi.py`; keep `_common.py` as-is.
6. `pipelines/` — replace the appointment_reminder family with yours (see
   below); keep `pipelines/shared/` as-is.
7. `tests/` — keep `test_openapi_app_builds.py`; adapt the unit tests as
   patterns 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

Copy `pipelines/appointment_reminder/` as the family pattern:

    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. The worker maps `job.kind` to a handler in its `HANDLERS`
dispatch table. See standards "50_pipeline_scaffold" and "51_worker_and_progress".

## 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)                 |
| `interfaces/_common.py`      | Nothing (reuse as-is)                 |
| `pipelines/shared/`          | Nothing (reuse as-is)                 |
| `pipelines/appointment_reminder/` | Family name, stages, patterns     |
| worker poll + dispatch loop  | Job kinds, 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")`.