46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
# 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.
|