# 🧩 Standards — the Aetos App Blueprint

One reusable architecture for every backend application in the Aetos ecosystem:
a spec-first HTTP edge, a pure domain core, a pluggable infrastructure layer,
and a single composition root.

Fill in **two axes only** and a new app is done: your **resource model**, and
(if needed) your **pipeline family**. The blueprint itself never names a
business domain — expenses, health metrics, inventory, and analytics are all
the same shape underneath.

> **Doc model:** this wiki is written for humans — how-to guides, the build
> recipe, and quality gates. The enforceable rules (layering, composition root,
> CRUD template, pipeline scaffold) and the library registry live in the
> **reference** pages, mirrored by the machine-readable `standards` MCP bundle.
> Query `find_library` before writing any infrastructure.

---

## 🚀 Key Features

- 🧭 **Spec-first routing** — the OpenAPI document, not decorator routers, is
  the source of truth (operationId lookup)
- 🏗️ **One-way layering** — `interfaces → domain → infra`, enforced
- 🔌 **Single composition root** — every dependency is wired in exactly one place
- 🧩 **Generic, not app-specific** — reusable rules versus two authoring axes
- 📚 **Library-backed** — DB, DI, pipelines, ingestion, auth, and docs come from
  internal libraries, never hand-written
- 🚦 **Explicit state machines** — durable job statuses, progress, and
  human-in-the-loop pauses

---

## 📁 Documentation Structure

| Section                                             | Description                                            |
|-----------------------------------------------------|--------------------------------------------------------|
| [Overview](01_overview.md)                          | Philosophy, the one-way dependency rule, architecture  |
| [App Components](02_components.md)                  | The component model and how the pieces wire together   |
| [Build Recipe](03_build_recipe.md)                  | The ordered, agentic checklist for a new app           |
| [Testing & Quality](04_development/01_testing.md)   | Test layout and acceptance gates                       |

**Reference** (separate site, mirrors the MCP bundle): the enforceable
rules — [Layering](../lib/02_layering_rules/), [Composition
Root](../lib/03_composition_root/), [Spec-First
Routing](../lib/04_spec_first_routing/), [CRUD
Template](../lib/05_crud_template/), [Pipeline
Scaffold](../lib/06_pipeline_scaffold/), [Worker &
Progress](../lib/07_worker_and_progress/), [Human-in-the-Loop](../lib/08_human_in_loop/),
[Infra Adapters](../lib/09_infra_adaptors/), [Genericity
Matrix](../lib/12_genericity_matrix/), [Library
Registry](../lib/13_library_registry/).

---

## 🔗 Related Resources

- **MCP bundle** — `standards` server on `:8009`: read `doc://index`,
  `doc://nav`, `doc://modules/{module}`; call `find_library(capability)`
- **Library registry** — the catalog of internal libraries behind every app
  (`libraries.json`, served as `registry://libraries`)
- **Template** — the runnable skeleton at `standards/src/templates/app/`
- **Copy the repo's `AGENTS.md`-style build prompt** from
  [Build Recipe](03_build_recipe.md)

---

© Aetoskia Internal — `standards`