Files
docs/standards/wiki/01_overview/index.html
Vishesh 'ironeagle' Bangotra f8cf35de0e Phase 8: add the Reference App wiki walkthrough (06_reference_app)
- four pages walking the vet sample: overview, domain & API, pipelines &
  worker, spec-driven client admin
- mkdocs nav section, index + start-an-app cross links
- bundle now exposes the walkthrough as wiki_reference_app_* modules
2026-10-20 15:02:11 +05:30

1056 lines
24 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="The philosophy and prompts behind the standardized application blueprint.">
<link rel="prev" href="..">
<link rel="next" href="../02_components/">
<link rel="icon" href="../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.23">
<title>Overview - Aetos Standards — Wiki</title>
<link rel="stylesheet" href="../assets/stylesheets/main.84d31ad4.min.css">
<link rel="stylesheet" href="../assets/stylesheets/palette.06af60db.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i%7CJetBrains+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Inter";--md-code-font:"JetBrains Mono"}</style>
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr" data-md-color-scheme="slate" data-md-color-primary="deep-purple" data-md-color-accent="cyan">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#overview" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="Aetos Standards — Wiki" class="md-header__button md-logo" aria-label="Aetos Standards — Wiki" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Aetos Standards — Wiki
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Overview
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="deep-purple" data-md-color-accent="cyan" aria-hidden="true" type="radio" name="__palette" id="__palette_0">
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
</a>
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href=".." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="./" class="md-tabs__link">
Overview
</a>
</li>
<li class="md-tabs__item">
<a href="../02_components/" class="md-tabs__link">
App Components
</a>
</li>
<li class="md-tabs__item">
<a href="../03_start_an_app/" class="md-tabs__link">
Start an App
</a>
</li>
<li class="md-tabs__item">
<a href="../06_reference_app/01_overview/" class="md-tabs__link">
Reference App
</a>
</li>
<li class="md-tabs__item">
<a href="../05_mcp_setup/" class="md-tabs__link">
MCP
</a>
</li>
<li class="md-tabs__item">
<a href="../04_development/01_testing/" class="md-tabs__link">
Testing & Quality
</a>
</li>
<li class="md-tabs__item">
<a href="../04_development/02_releasing/" class="md-tabs__link">
Releasing & Versioning
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted md-nav--integrated" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="Aetos Standards — Wiki" class="md-nav__button md-logo" aria-label="Aetos Standards — Wiki" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>
</a>
Aetos Standards — Wiki
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Overview
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Overview
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#architecture" class="md-nav__link">
<span class="md-ellipsis">
🏗️ Architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#the-one-way-dependency-rule" class="md-nav__link">
<span class="md-ellipsis">
🔄 The one-way dependency rule
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#core-principles" class="md-nav__link">
<span class="md-ellipsis">
🧭 Core principles
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#runtime-processes" class="md-nav__link">
<span class="md-ellipsis">
⚙️ Runtime processes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#read-next" class="md-nav__link">
<span class="md-ellipsis">
➡️ Read Next
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../02_components/" class="md-nav__link">
<span class="md-ellipsis">
App Components
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../03_start_an_app/" class="md-nav__link">
<span class="md-ellipsis">
Start an App
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_5" >
<label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-ellipsis">
Reference App
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Reference App
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../06_reference_app/01_overview/" class="md-nav__link">
<span class="md-ellipsis">
Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../06_reference_app/02_domain_and_api/" class="md-nav__link">
<span class="md-ellipsis">
Domain & API
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../06_reference_app/03_pipelines_and_worker/" class="md-nav__link">
<span class="md-ellipsis">
Pipelines & Worker
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../06_reference_app/04_client_admin/" class="md-nav__link">
<span class="md-ellipsis">
Client Admin
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_6" >
<label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
<span class="md-ellipsis">
MCP
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_6">
<span class="md-nav__icon md-icon"></span>
MCP
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../05_mcp_setup/" class="md-nav__link">
<span class="md-ellipsis">
Setup
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../04_development/01_testing/" class="md-nav__link">
<span class="md-ellipsis">
Testing & Quality
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../04_development/02_releasing/" class="md-nav__link">
<span class="md-ellipsis">
Releasing & Versioning
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="overview">Overview</h1>
<p>The blueprint is a <strong>hexagonal (ports &amp; adapters) application</strong> with a
<strong>spec-first</strong> web edge and a <strong>single composition root</strong>. It favors explicit
wiring over implicit magic and existing internal libraries over hand-written
infrastructure. Start here to build the mental model; the enforceable details
live in the reference pages.</p>
<hr />
<h2 id="architecture">🏗️ Architecture</h2>
<pre class="mermaid"><code>flowchart LR
subgraph EDGE["interfaces/ — HTTP edge"]
OAS["openapi.yaml&lt;br/&gt;operationId contract"]
RT["&lt;resource&gt;/routes.py&lt;br/&gt;thin handlers"]
end
subgraph CORE["domain/ — business core"]
MD["models"]
PT["ports (adapter binding seam)"]
SV["services"]
end
subgraph INFRA["infra/ — adapters"]
RP["mongo repos (mongo-ops)"]
AD["cache · stores · llm · mail"]
DB[("MongoDB")]
end
CR["init.py&lt;br/&gt;composition root"]
OAS --&gt; RT
RT --&gt; SV
SV --&gt; PT
SV --&gt; RP
PT -. depends on .- RP
CR --- RT
CR --- SV
CR --- RP
RP --&gt; DB
AD --- CR</code></pre>
<p>The rule holds at every edge: code in an outer ring may depend on a ring closer
to the core, never the reverse. <code>domain/</code> never imports a web framework;
only its <code>ports/</code> seam reaches into <code>infra/</code> to bind adapters.</p>
<blockquote>
<p><strong>Legend</strong> — solid arrows are compile-time calls; dotted arrows are the
port/adapter binding, performed by the composition root at startup.</p>
</blockquote>
<hr />
<h2 id="the-one-way-dependency-rule">🔄 The one-way dependency rule</h2>
<table>
<thead>
<tr>
<th>Ring</th>
<th>May import</th>
<th>Never imports</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>interfaces/</code></td>
<td><code>domain</code>, framework glue (glue only)</td>
<td>business logic, <code>infra</code> directly</td>
</tr>
<tr>
<td><code>domain/</code></td>
<td>its own models + its <code>ports/</code> seam (which binds <code>infra</code>/libraries)</td>
<td>web frameworks, <code>interfaces/</code></td>
</tr>
<tr>
<td><code>infra/</code></td>
<td><code>domain</code> ports, drivers, libraries</td>
<td>—</td>
</tr>
<tr>
<td><code>init.py</code></td>
<td>everything (the wiring point)</td>
<td>—</td>
</tr>
</tbody>
</table>
<hr />
<h2 id="core-principles">🧭 Core principles</h2>
<ol>
<li><strong>One-way dependencies.</strong> <code>interfaces -&gt; domain -&gt; infra</code> is allowed; the
reverse is forbidden.</li>
<li><strong>Ports in the domain, adapters in infra.</strong> A service depends on a port; the
port's factory binds the concrete adapter, and the composition root calls
those factories.</li>
<li><strong>One composition root.</strong> Nothing constructs its own dependencies. All
wiring lives in one module (<code>init.py</code>) exposed as a flat resource registry.</li>
<li><strong>Spec-first.</strong> The HTTP contract is declared in <code>openapi.yaml</code>; route
handlers are looked up by <code>operationId</code>. There are no decorator routers.</li>
<li><strong>Reuse the libraries.</strong> Orchestration, DI, Mongo repositories, ingestion,
auth, and docs come from internal libraries — see the <a href="../../lib/93_library_registry/">Library
Registry</a>.</li>
<li><strong>Explicit state machines.</strong> Long-running work moves through explicit,
durable statuses and can pause for human input.</li>
</ol>
<hr />
<h2 id="runtime-processes">⚙️ Runtime processes</h2>
<p>A standard app may run as up to three processes that share the same composition
root:</p>
<table>
<thead>
<tr>
<th>Process</th>
<th>Entry point</th>
<th>Responsibility</th>
</tr>
</thead>
<tbody>
<tr>
<td>API</td>
<td><code>main.py</code></td>
<td>serve HTTP; start/stop resources via lifespan</td>
</tr>
<tr>
<td>Worker</td>
<td><code>worker.py</code></td>
<td>poll durable jobs, run pipelines, publish progress</td>
</tr>
<tr>
<td>Scripts</td>
<td><code>python -m scripts.&lt;name&gt;</code></td>
<td>one-shot operator tasks</td>
</tr>
</tbody>
</table>
<hr />
<h2 id="read-next">➡️ Read Next</h2>
<ul>
<li><a href="../02_components/">02 – App Components</a> · <a href="../03_start_an_app/">03 – Start an App</a></li>
</ul>
</article>
</div>
<script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "..", "features": ["navigation.sections", "navigation.expand", "navigation.top", "navigation.instant", "navigation.tracking", "navigation.indexes", "navigation.tabs", "toc.integrate", "header.autohide", "content.code.copy", "content.code.annotate", "content.tabs.link", "content.action.edit", "search.highlight", "search.share", "search.suggest"], "search": "../assets/javascripts/workers/search.973d3a69.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<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>