fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(html): di + data-flow explainers reflect BindContext

Browse Source
This commit is contained in:
Danijel Martinek
2026-05-09 12:51:15 +02:00
parent 1e8b3f2364
commit 990f641425
2 changed files with 11 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/architecture/data-flow-explainer.html
View File

@@ -1664,7 +1664,7 @@ footer .colophon {
</div>
<div class="di-card">
<h4>Two binding modes, one symbol.</h4>
<p>The <code>BlogModule</code> binds <code>IArticlesRepository</code> to <code>MockArticlesRepository</code> by default — useful at dev/test time. At app boot, <code>bindProductionBlog(config, tracer, logger, bus, queue)</code> unbinds the symbol and rebinds it to <code>new ArticlesRepository(config, tracer, logger)</code>. Use cases and controllers don't notice — they get whatever the symbol currently resolves to.</p>
<p>The <code>BlogModule</code> binds <code>IArticlesRepository</code> to <code>MockArticlesRepository</code> by default — useful at dev/test time. At app boot, <code>bindProductionBlog(ctx: BindProductionContext)</code> unbinds the symbol and rebinds it to <code>new ArticlesRepository(ctx.config, ctx.tracer, ctx.logger)</code>. Use cases and controllers don't notice — they get whatever the symbol currently resolves to. The <code>ctx</code> object is built once by the app aggregator and passed to all feature binders.</p>
<p>This is also why the boundary stays clean: features don't import <code>core-cms</code>; the app passes the Payload config in.</p>
</div>
</div>
@@ -1701,8 +1701,9 @@ footer .colophon {
<div class="cf-card">
<div class="cf-tag">app boot · production override</div>
<h3>blog/di/<em>bind-production.ts</em></h3>
<p>Called from each app's bootstrap (<code>apps/web-next/src/server/bind-production.ts</code>) with the resolved Payload config.</p>
<pre class="code" data-lang="typescript // packages/blog/src/di/bind-production.ts"><span class="k">export function</span> <span class="n">bindProductionBlog</span>(<span class="n">config</span>: <span class="t">SanitizedConfig</span>): <span class="t">void</span> {
<p>Called from each app's bootstrap (<code>apps/web-next/src/server/bind-production.ts</code>) with the <code>ctx</code> object built once by the aggregator. <code>BindProductionContext</code> is imported from <code>@repo/core-shared/di</code>.</p>
<pre class="code" data-lang="typescript // packages/blog/src/di/bind-production.ts"><span class="k">export function</span> <span class="n">bindProductionBlog</span>(<span class="n">ctx</span>: <span class="t">BindProductionContext</span>): <span class="t">void</span> {
<span class="k">const</span> { <span class="n">config</span>, <span class="n">tracer</span>, <span class="n">logger</span>, <span class="n">bus</span>, <span class="n">queue</span>, <span class="n">realtime</span>, <span class="n">realtimeRegistry</span> } = <span class="n">ctx</span>;
<span class="k">if</span> (<span class="n">blogContainer</span>.<span class="n">isBound</span>(<span class="n">BLOG_SYMBOLS</span>.<span class="n">IArticlesRepository</span>)) {
<span class="n">blogContainer</span>.<span class="n">unbind</span>(<span class="n">BLOG_SYMBOLS</span>.<span class="n">IArticlesRepository</span>);
}
@@ -1773,7 +1774,7 @@ footer .colophon {
<p style="margin-top: 32px;"><strong>The mock is reached from two directions.</strong> Both are legitimate, neither is "the test version":</p>
<ol class="role-jobs">
<li><strong>By the DI container at runtime.</strong> <code>BlogModule</code> binds <code>IArticlesRepository</code> to <code>MockArticlesRepository</code> at module-load time. Anything resolving that symbol — use cases, controllers, tRPC procedures, the dev server — gets the mock until <code>bindProductionBlog(config, tracer, logger, bus, queue)</code> swaps it for the real Payload-backed one. See §03.</li>
<li><strong>By the DI container at runtime.</strong> <code>BlogModule</code> binds <code>IArticlesRepository</code> to <code>MockArticlesRepository</code> at module-load time. Anything resolving that symbol — use cases, controllers, tRPC procedures, the dev server — gets the mock until <code>bindProductionBlog(ctx: BindProductionContext)</code> swaps it for the real Payload-backed one. See §03.</li>
<li><strong>By tests, via direct construction.</strong> Unit tests skip the container entirely. They construct the mock with <code>new MockArticlesRepository()</code> and pass it directly into the use-case factory function. Same class, different consumer — just a closure with a fake repo.</li>
</ol>
@@ -1786,7 +1787,7 @@ footer .colophon {
<details class="cf-detail">
<summary>show: the mock as DI binding (in module.ts)</summary>
<div class="detail-body">
<p>This is from <code>packages/blog/src/di/module.ts</code> — the very first binding in the module is the mock. Everything downstream (use cases, controllers) resolves through this default. <code>bindProductionBlog(config, tracer, logger, bus, queue)</code> later replaces only this one line at app boot — use case + controller bindings stay put.</p>
<p>This is from <code>packages/blog/src/di/module.ts</code> — the very first binding in the module is the mock. Everything downstream (use cases, controllers) resolves through this default. <code>bindProductionBlog(ctx: BindProductionContext)</code> later replaces only this one line at app boot — use case + controller bindings stay put.</p>
<pre class="code" data-lang="typescript // packages/blog/src/di/module.ts"><span class="k">export const</span> <span class="n">BlogModule</span> = <span class="k">new</span> <span class="t">ContainerModule</span>((<span class="n">bind</span>) =&gt; {
<span class="c">// 1) Mock is the DEFAULT binding for the repo symbol.</span>
<span class="c">// Dev server, unit tests, storybook all resolve to this.</span>
@@ -2191,7 +2192,7 @@ footer .colophon {
<div class="tradeoff-card">
<div class="tag">di/bind-production.ts</div>
<h3>Production binder</h3>
<p class="blurb"><code>bindProduction&lt;F&gt;(config)</code> — unbinds the mock, rebinds the real Payload-backed impl.</p>
<p class="blurb"><code>bindProduction&lt;F&gt;(ctx: BindProductionContext)</code> — unbinds the mock, rebinds the real Payload-backed impl. The <code>ctx</code> arg carries required fields (<code>tracer</code>, <code>logger</code>, <code>config</code>) and optional cross-cutting deps (<code>bus</code>, <code>queue</code>, <code>realtime</code>, <code>realtimeRegistry</code>).</p>
<div class="pc-cols">
<div class="pros"><h5>Pros</h5><ul>
<li>Decouples Payload config from the feature package — boundary stays clean</li>