docs(standards): mirror doc-forge wiki style; mermaid + copyable build prompt
- move templates into src/templates; renumber wiki pages; add app-components page - embed agentic build prompt as a copyable markdown block; add mermaid diagrams - build.py writes <name>/mcp; config static bundle -> standards/mcp - registry reads libraries.json as bytes (committed file was UTF-16LE); normalize to UTF-8 - Dockerfile: drop stale blog copy; per-repo <name>/mcp copies - drop nested standards/mcp/standards duplicate and empty root mcp/
This commit is contained in:
@@ -72,7 +72,7 @@
|
||||
<div data-md-component="skip">
|
||||
|
||||
|
||||
<a href="#the-aetos-standard-app-blueprint" class="md-skip">
|
||||
<a href="#standards-the-aetos-app-blueprint" class="md-skip">
|
||||
Skip to content
|
||||
</a>
|
||||
|
||||
@@ -273,18 +273,27 @@
|
||||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#how-to-read-this" class="md-nav__link">
|
||||
<a href="#key-features" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
How to read this
|
||||
🚀 Key Features
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#for-ai-agents" class="md-nav__link">
|
||||
<a href="#documentation-structure" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
For AI agents
|
||||
📁 Documentation Structure
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#related-resources" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
🔗 Related Resources
|
||||
</span>
|
||||
</a>
|
||||
|
||||
@@ -327,12 +336,12 @@
|
||||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="10_testing/" class="md-nav__link">
|
||||
<a href="02_components/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
<span class="md-ellipsis">
|
||||
Testing
|
||||
App Components
|
||||
|
||||
</span>
|
||||
|
||||
@@ -349,7 +358,7 @@
|
||||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="11_build_recipe/" class="md-nav__link">
|
||||
<a href="03_build_recipe/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
@@ -364,6 +373,28 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="04_development/01_testing/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
<span class="md-ellipsis">
|
||||
Testing & Quality
|
||||
|
||||
</span>
|
||||
|
||||
|
||||
</a>
|
||||
</li>
|
||||
|
||||
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
</div>
|
||||
@@ -391,18 +422,27 @@
|
||||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#how-to-read-this" class="md-nav__link">
|
||||
<a href="#key-features" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
How to read this
|
||||
🚀 Key Features
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#for-ai-agents" class="md-nav__link">
|
||||
<a href="#documentation-structure" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
For AI agents
|
||||
📁 Documentation Structure
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#related-resources" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
🔗 Related Resources
|
||||
</span>
|
||||
</a>
|
||||
|
||||
@@ -424,92 +464,85 @@
|
||||
|
||||
|
||||
|
||||
<h1 id="the-aetos-standard-app-blueprint">The Aetos Standard App Blueprint</h1>
|
||||
<p>A single, reusable architecture for backend applications in the Aetos ecosystem.</p>
|
||||
<p>Every application built with this blueprint has the same shape:</p>
|
||||
<ul>
|
||||
<li>a <strong>spec-first HTTP layer</strong> driven by an OpenAPI document;</li>
|
||||
<li>a <strong>domain layer</strong> of pure models, ports, and services;</li>
|
||||
<li>an <strong>infrastructure layer</strong> of adapters (MongoDB, cache, workers, LLM, mail);</li>
|
||||
<li>a <strong>composition root</strong> that wires everything in exactly one place;</li>
|
||||
<li>an optional <strong>pipeline layer</strong> for data-driven extraction/enrichment;</li>
|
||||
<li>an optional <strong>background worker</strong> that runs long-running jobs and reports progress.</li>
|
||||
</ul>
|
||||
<h1 id="standards-the-aetos-app-blueprint">🧩 Standards — the Aetos App Blueprint</h1>
|
||||
<p>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.</p>
|
||||
<p>Fill in <strong>two axes only</strong> and a new app is done: your <strong>resource model</strong>, and
|
||||
(if needed) your <strong>pipeline family</strong>. The blueprint itself never names a
|
||||
business domain — expenses, health metrics, inventory, and analytics are all
|
||||
the same shape underneath.</p>
|
||||
<blockquote>
|
||||
<p>This blueprints is deliberately <strong>app-agnostic</strong>. It never names a concrete
|
||||
business domain. Any application — expenses, health metrics, inventory,
|
||||
analytics — is produced by filling in <strong>two axes only</strong>: the resource model
|
||||
and (if needed) the pipeline family.</p>
|
||||
<p><strong>Doc model:</strong> 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
|
||||
<strong>reference</strong> pages, mirrored by the machine-readable <code>standards</code> MCP bundle.
|
||||
Query <code>find_library</code> before writing any infrastructure.</p>
|
||||
</blockquote>
|
||||
<h2 id="how-to-read-this">How to read this</h2>
|
||||
<hr />
|
||||
<h2 id="key-features">🚀 Key Features</h2>
|
||||
<ul>
|
||||
<li>🧭 <strong>Spec-first routing</strong> — the OpenAPI document, not decorator routers, is
|
||||
the source of truth (operationId lookup)</li>
|
||||
<li>🏗️ <strong>One-way layering</strong> — <code>interfaces → domain → infra</code>, enforced</li>
|
||||
<li>🔌 <strong>Single composition root</strong> — every dependency is wired in exactly one place</li>
|
||||
<li>🧩 <strong>Generic, not app-specific</strong> — reusable rules versus two authoring axes</li>
|
||||
<li>📚 <strong>Library-backed</strong> — DB, DI, pipelines, ingestion, auth, and docs come from
|
||||
internal libraries, never hand-written</li>
|
||||
<li>🚦 <strong>Explicit state machines</strong> — durable job statuses, progress, and
|
||||
human-in-the-loop pauses</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="documentation-structure">📁 Documentation Structure</h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Page</th>
|
||||
<th>What it covers</th>
|
||||
<th>Section</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Overview</td>
|
||||
<td>The philosophy and the one-way dependency rule</td>
|
||||
<td><a href="01_overview/">Overview</a></td>
|
||||
<td>Philosophy, the one-way dependency rule, architecture</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Layering Rules</td>
|
||||
<td>Which package may import which</td>
|
||||
<td><a href="02_components/">App Components</a></td>
|
||||
<td>The component model and how the pieces wire together</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Composition Root</td>
|
||||
<td>The single wiring point</td>
|
||||
<td><a href="03_build_recipe/">Build Recipe</a></td>
|
||||
<td>The ordered, agentic checklist for a new app</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Spec-First Routing</td>
|
||||
<td>OpenAPI as the source of truth</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>CRUD Template</td>
|
||||
<td>The canonical resource slice</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Pipeline Scaffold</td>
|
||||
<td>Data-driven processing families</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Worker & Progress</td>
|
||||
<td>Async jobs, status machine, streaming progress</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Human-in-the-Loop</td>
|
||||
<td>Pausing a job to ask a question</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Infra Adapters</td>
|
||||
<td>MongoDB, cache, stores, LLM, mail</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Testing</td>
|
||||
<td>Integration + unit conventions</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Build Recipe</td>
|
||||
<td>The ordered checklist to generate a new app</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Genericity Matrix</td>
|
||||
<td>What is reusable vs what you must write</td>
|
||||
<td><a href="04_development/01_testing/">Testing & Quality</a></td>
|
||||
<td>Test layout and acceptance gates</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h2 id="for-ai-agents">For AI agents</h2>
|
||||
<p>This content is served as MCP resources under <code>docs://index</code>, <code>docs://nav</code>,
|
||||
and <code>docs://modules/{module}</code>. To build a new app:</p>
|
||||
<ol>
|
||||
<li>Read <code>build_recipe</code> first.</li>
|
||||
<li>Read <code>genericity_matrix</code> to know what you must author.</li>
|
||||
<li>Query the <strong>library registry</strong> (<code>find_library</code>) before writing any
|
||||
infrastructure yourself.</li>
|
||||
<li>Copy the <code>templates/</code> skeleton and fill the two app-specific axes.</li>
|
||||
</ol>
|
||||
<p><strong>Reference</strong> (separate site, mirrors the MCP bundle): the enforceable
|
||||
rules — <a href="../lib/02_layering_rules/">Layering</a>, <a href="../lib/03_composition_root/">Composition
|
||||
Root</a>, <a href="../lib/04_spec_first_routing/">Spec-First
|
||||
Routing</a>, <a href="../lib/05_crud_template/">CRUD
|
||||
Template</a>, <a href="../lib/06_pipeline_scaffold/">Pipeline
|
||||
Scaffold</a>, <a href="../lib/07_worker_and_progress/">Worker &
|
||||
Progress</a>, <a href="../lib/08_human_in_loop/">Human-in-the-Loop</a>,
|
||||
<a href="../lib/09_infra_adaptors/">Infra Adapters</a>, <a href="../lib/12_genericity_matrix/">Genericity
|
||||
Matrix</a>, <a href="../lib/13_library_registry/">Library
|
||||
Registry</a>.</p>
|
||||
<hr />
|
||||
<h2 id="related-resources">🔗 Related Resources</h2>
|
||||
<ul>
|
||||
<li><strong>MCP bundle</strong> — <code>standards</code> server on <code>:8009</code>: read <code>doc://index</code>,
|
||||
<code>doc://nav</code>, <code>doc://modules/{module}</code>; call <code>find_library(capability)</code></li>
|
||||
<li><strong>Library registry</strong> — the catalog of internal libraries behind every app
|
||||
(<code>libraries.json</code>, served as <code>registry://libraries</code>)</li>
|
||||
<li><strong>Template</strong> — the runnable skeleton at <code>standards/src/templates/app/</code></li>
|
||||
<li><strong>Copy the repo's <code>AGENTS.md</code>-style build prompt</strong> from
|
||||
<a href="03_build_recipe/">Build Recipe</a></li>
|
||||
</ul>
|
||||
<hr />
|
||||
<p>© Aetoskia Internal — <code>standards</code></p>
|
||||
|
||||
|
||||
|
||||
@@ -571,6 +604,8 @@ and <code>docs://modules/{module}</code>. To build a new app:</p>
|
||||
|
||||
<script src="assets/javascripts/bundle.f55a23d4.min.js"></script>
|
||||
|
||||
<script src="https://unpkg.com/mermaid@10.9.1/dist/mermaid.min.js"></script>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user