docs(standards): align layering docs with the port seam; split runtime vs wiring diagrams

This commit is contained in:
2026-10-12 13:15:35 +05:30
parent 8a10c4768c
commit 7d1694148a
25 changed files with 230 additions and 159 deletions

View File

@@ -553,9 +553,9 @@ live in the reference pages.</p>
RT["&lt;resource&gt;/routes.py&lt;br/&gt;thin handlers"]
end
subgraph CORE["domain/ — pure business core"]
subgraph CORE["domain/ — business core"]
MD["models"]
PT["ports (abstract)"]
PT["ports (adapter binding seam)"]
SV["services"]
end
@@ -578,11 +578,11 @@ live in the reference pages.</p>
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 or a
database driver.</p>
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 contract, resolved by the composition root at startup.</p>
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>
@@ -602,8 +602,8 @@ port/adapter contract, resolved by the composition root at startup.</p>
</tr>
<tr>
<td><code>domain/</code></td>
<td>nothing but its own ports</td>
<td>web frameworks, drivers, <code>infra</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>
@@ -622,8 +622,9 @@ port/adapter contract, resolved by the composition root at startup.</p>
<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 an abstract
port; the composition root injects a concrete adapter.</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