# 🧩 Standards — the Aetos App Blueprint

One reusable architecture for every backend application in the Aetos ecosystem:
a spec-first HTTP edge, a framework-free 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   |
| [Start an App](03_start_an_app.md)                  | The entry point: gather the two axes, then build       |
| [Reference App](06_reference_app/01_overview.md)    | The runnable vet sample — server, pipelines, client    |
| [Testing & Quality](04_development/01_testing.md)   | Test layout and acceptance gates                       |

**Reference** (separate site, mirrors the MCP bundle): the enforceable
anatomy — start at the [Build Recipe](../lib/01_build_recipe/), then the
pillars: domains ([Layering](../lib/10_layering_rules/)), the OpenAPI
contract ([Composition Root](../lib/02_composition_root/),
[Spec-First Routing](../lib/20_spec_first_routing/), [CRUD
Template](../lib/21_crud_template/), [Auth
Integration](../lib/22_auth_integration/)), interfaces & infra ([Infra
Adapters](../lib/30_infra_adaptors/)), UI ([Auto-Rendered
Admin](../lib/40_ui_admin/)), the optional pipelines layer ([Pipeline
Scaffold](../lib/50_pipeline_scaffold/), [Worker &
Progress](../lib/51_worker_and_progress/), [Human-in-the-Loop](../lib/52_human_in_loop/)),
and delivery/meta ([Genericity
Matrix](../lib/92_genericity_matrix/), [Library
Registry](../lib/93_library_registry/)).

---

## 🔗 Related Resources

- **MCP bundle** — `standards` server on `:8009`: read `docs://index`,
  `docs://nav`, `docs://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 sample at `standards/src/templates/app/`
  (server) and `standards/src/templates/client/` (React admin); walkthrough in
  the [Reference App](06_reference_app/01_overview.md)
- **Start a build** — invoke the `start_app` prompt on the `standards` server,
  or read the [Start an App](03_start_an_app.md) guide

---

© Aetoskia Internal — `standards`