docs(standards): vendor template into MCP bundle; add component tools + start_app prompt
This commit is contained in:
@@ -691,7 +691,9 @@
|
||||
<h1 id="infra-adapters">Infra Adapters</h1>
|
||||
<h2 id="summary">Summary</h2>
|
||||
<p>All external systems are reached through adapters in <code>infra/</code>. Prefer an
|
||||
existing internal library over writing a new adapter.</p>
|
||||
existing internal library over writing a new adapter; where no library exists,
|
||||
copy the Tier B scaffold from <code>templates/app</code>. See the Genericity Matrix for the
|
||||
Tier A / B / C split.</p>
|
||||
<hr />
|
||||
<h2 id="database-mongodb">Database (MongoDB)</h2>
|
||||
<ul>
|
||||
@@ -720,9 +722,10 @@ existing internal library over writing a new adapter.</p>
|
||||
<ul>
|
||||
<li>Transactions use a session context manager provided by the library.</li>
|
||||
</ul>
|
||||
<p><strong>Library:</strong> the Mongo operations library (see registry). Do not write raw
|
||||
Motor calls in the domain.</p>
|
||||
<p><strong>Tier A — Library (Mongo Ops).</strong> Do not write raw Motor calls in the domain;
|
||||
consult the registry and the library's MCP before touching the driver.</p>
|
||||
<h2 id="http-response-cache">HTTP response cache</h2>
|
||||
<p><strong>Tier B — template.</strong> Copy from <code>templates/app</code>; not a standalone library.</p>
|
||||
<p>A generic GET cache sits behind a decorator.</p>
|
||||
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span>
|
||||
<span class="normal"><a href="#__codelineno-2-2">2</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1"></a><span class="nd">@cache_response</span><span class="p">(</span><span class="n">ttl</span><span class="o">=</span><span class="mi">60</span><span class="p">)</span>
|
||||
@@ -735,14 +738,16 @@ Motor calls in the domain.</p>
|
||||
invalidation.</li>
|
||||
</ul>
|
||||
<h2 id="event-progress-bus">Event / progress bus</h2>
|
||||
<p><strong>Tier B — template.</strong> Copy from <code>templates/app</code>.</p>
|
||||
<p>A port with an in-memory default adapter (<code>publish</code>, <code>get_events</code>). Swap for a
|
||||
durable broker in production (see Worker & Progress).</p>
|
||||
<h2 id="external-clients-ingestion">External clients (ingestion)</h2>
|
||||
<p>External fetchers (files, mail, HTTP) are adapters that wrap ingestion
|
||||
libraries. Construct them in the composition root and inject into
|
||||
orchestrators.</p>
|
||||
<p><strong>Libraries:</strong> the ingestion library (formats) and the mail library (email).</p>
|
||||
<p><strong>Tier A — Libraries:</strong> Omniread (formats) and Mail Intake (email).</p>
|
||||
<h2 id="llm-clients">LLM clients</h2>
|
||||
<p><strong>Tier B — template.</strong> Copy the pool scaffold from <code>templates/app</code>.</p>
|
||||
<p>When a pipeline calls a model provider, route through a pool adaptor that
|
||||
handles provider selection, retries, and client lifecycle:</p>
|
||||
<div class="language-python highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-3-1">1</a></span>
|
||||
@@ -751,11 +756,19 @@ handles provider selection, retries, and client lifecycle:</p>
|
||||
</span></code></pre></div></td></tr></table></div>
|
||||
<p>Providers are selected by <code>LLM_PROVIDER</code> and configured by environment.</p>
|
||||
<h2 id="key-value-store">Key-value store</h2>
|
||||
<p><strong>Tier B — template.</strong> Copy from <code>templates/app</code>.</p>
|
||||
<p>For report/snapshot storage, provide a pluggable store port with a Redis
|
||||
adapter and an in-memory fallback.</p>
|
||||
<h2 id="rule">Rule</h2>
|
||||
<p>If a capability already exists as a library (DB, DI, ingestion, mail, auth,
|
||||
docs), <strong>use it</strong>. Writing a private copy of a library is a defect.</p>
|
||||
<ul>
|
||||
<li><strong>Tier A (libraries: DB, DI, ingestion, mail, auth, docs, pipelines)</strong> — use
|
||||
the library; writing a private copy is a defect. Query <code>find_library</code> first.</li>
|
||||
<li><strong>Tier B (cache, progress bus, LLM pool, KV store, composition shape, worker,
|
||||
tests)</strong> — these are template code, not libraries: copy them from
|
||||
<code>templates/app</code> rather than searching the registry.</li>
|
||||
<li><strong>Tier C (models, business logic, pipeline families, rules)</strong> — author them
|
||||
yourself.</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user