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.