# The Aetos Standard App Blueprint

A single, reusable architecture for backend applications in the Aetos ecosystem.

Every application built with this blueprint has the same shape:

- a **spec-first HTTP layer** driven by an OpenAPI document;
- a **domain layer** of pure models, ports, and services;
- an **infrastructure layer** of adapters (MongoDB, cache, workers, LLM, mail);
- a **composition root** that wires everything in exactly one place;
- an optional **pipeline layer** for data-driven extraction/enrichment;
- an optional **background worker** that runs long-running jobs and reports progress.

> This blueprints is deliberately **app-agnostic**. It never names a concrete
> business domain. Any application — expenses, health metrics, inventory,
> analytics — is produced by filling in **two axes only**: the resource model
> and (if needed) the pipeline family.

## How to read this

| Page | What it covers |
|---|---|
| Overview | The philosophy and the one-way dependency rule |
| Layering Rules | Which package may import which |
| Composition Root | The single wiring point |
| Spec-First Routing | OpenAPI as the source of truth |
| CRUD Template | The canonical resource slice |
| Pipeline Scaffold | Data-driven processing families |
| Worker & Progress | Async jobs, status machine, streaming progress |
| Human-in-the-Loop | Pausing a job to ask a question |
| Infra Adapters | MongoDB, cache, stores, LLM, mail |
| Testing | Integration + unit conventions |
| Build Recipe | The ordered checklist to generate a new app |
| Genericity Matrix | What is reusable vs what you must write |

## For AI agents

This content is served as MCP resources under `docs://index`, `docs://nav`,
and `docs://modules/{module}`. To build a new app:

1. Read `build_recipe` first.
2. Read `genericity_matrix` to know what you must author.
3. Query the **library registry** (`find_library`) before writing any
   infrastructure yourself.
4. Copy the `templates/` skeleton and fill the two app-specific axes.