mtp-docs/docs/02-architecture.html at main · paramhq/mtp-docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>02 · Architecture — Multi-Tenant Platform</title>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Fraunces:opsz,wght@9..144,500;9..144,600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" />
<link rel="stylesheet" href="../assets/styles.css" />
</head>
<body>
<div class="layout">
  <aside class="sidebar">
    <a href="../index.html" class="brand">
      <span class="brand-mark">MTP</span>
      <span class="brand-text">Multi-Tenant Platform</span>
    </a>
    <nav>
      <div class="nav-group">
        <h4>Foundations</h4>
        <ul>
          <li><a href="../index.html"><span class="nav-num">00</span>Overview</a></li>
          <li><a href="01-findings.html"><span class="nav-num">01</span>Findings</a></li>
          <li><a href="02-architecture.html" class="active"><span class="nav-num">02</span>Architecture</a></li>
          <li><a href="10-tenancy-model.html"><span class="nav-num">10</span>Tenancy Model</a></li>
        </ul>
      </div>
      <div class="nav-group">
        <h4>Validation</h4>
        <ul>
          <li><a href="03-code-sketch.html"><span class="nav-num">03</span>Code Sketch</a></li>
          <li><a href="04-ui-rule-config.html"><span class="nav-num">04</span>UI Rule Config</a></li>
          <li><a href="05-result-pattern.html"><span class="nav-num">05</span>Result Pattern</a></li>
          <li><a href="06-reconciliation.html"><span class="nav-num">06</span>Reconciliation</a></li>
        </ul>
      </div>
      <div class="nav-group">
        <h4>Tenant Surface</h4>
        <ul>
          <li><a href="07-ui-schema.html"><span class="nav-num">07</span>UI Schema</a></li>
          <li><a href="08-i18n-l10n.html"><span class="nav-num">08</span>i18n / l10n</a></li>
          <li><a href="09-extension-fields.html"><span class="nav-num">09</span>Extension Fields</a></li>
        </ul>
      </div>
      <div class="nav-group">
        <h4>Frontend</h4>
        <ul>
          <li><a href="../mockups/classic.html"><span class="nav-num">UI1</span>AppShell &mdash; Classic</a></li>
          <li><a href="../mockups/zoho.html"><span class="nav-num">UI2</span>AppShell &mdash; 2-Stage</a></li>
          <li><a href="../mockups/exam-setup.html"><span class="nav-num">UI3</span>AppShell &mdash; Exam Setup</a></li>
          <li><a href="../mockups/ux-showcase-1.html"><span class="nav-num">UI4</span>AppShell &mdash; UX Showcase</a></li>
          <li><a href="../mockups/ux-showcase-2.html"><span class="nav-num">UI5</span>AppShell &mdash; UX Showcase 2</a></li>
          <li><a href="../mockups/ux-showcase-3.html"><span class="nav-num">UI6</span>AppShell &mdash; UX Showcase 3</a></li>
          <li><a href="../mockups/ux-showcase-4.html"><span class="nav-num">UI8</span>AppShell &mdash; UX Showcase 4</a></li>
          <li><a href="../mockups/ux-catalog.html"><span class="nav-num">UI7</span>UX Pattern Catalog</a></li>
          <li><a href="../mockups/notes.html"><span class="nav-num">UIN</span>AppShell Notes</a></li>
        </ul>
      </div>
      <div class="nav-group">
        <h4>Decisions</h4>
        <ul>
          <li><a href="../adr/0001-hybrid-validation-strategy.html"><span class="nav-num">ADR-1</span>Hybrid Validation</a></li>
          <li><a href="../adr/0002-database-per-client.html"><span class="nav-num">ADR-2</span>DB-per-Client</a></li>
          <li><a href="../adr/0003-frontend-stack.html"><span class="nav-num">ADR-3</span>Frontend Stack</a></li>
          <li><a href="../adr/0004-authorization-permission-model.html"><span class="nav-num">ADR-4</span>Authz &amp; Permissions</a></li>
          <li><a href="../adr/0005-repo-topology.html"><span class="nav-num">ADR-5</span>Repo Topology</a></li>
          <li><a href="../adr/0006-no-module-federation.html"><span class="nav-num">ADR-6</span>No Module Federation</a></li>
          <li><a href="../adr/0007-ui-stack-radix-cssmodules.html"><span class="nav-num">ADR-7</span>UI Stack &mdash; Radix</a></li>
          <li><a href="../adr/0008-mtp-web-folder-structure.html"><span class="nav-num">ADR-8</span>mtp-web Folder Structure</a></li>
          <li><a href="../adr/0009-hr-payroll-three-aggregates.html"><span class="nav-num">ADR-9</span>HR-Payroll &mdash; 3 Aggregates, 1 Module</a></li>
        </ul>
      </div>
      <div class="nav-group">
        <h4>GNUMS &mdash; Conventions</h4>
        <ul>
          <li><a href="../gnums/module-catalog.html"><span class="nav-num">MOD</span>Module Catalog</a></li>
          <li><a href="../gnums/all-modules-inventory.html"><span class="nav-num">REF</span>Procedure Inventory</a></li>
          <li><a href="../gnums/org-hierarchy.html"><span class="nav-num">ORG</span>Org Hierarchy</a></li>
          <li><a href="../gnums/hierarchy-comparison.html"><span class="nav-num">CMP</span>Hierarchy Comparison</a></li>
        </ul>
      </div>
      <div class="nav-group">
        <h4>GNUMS &mdash; Modules</h4>
        <ul>
          <li><a href="../gnums/methodology.html"><span class="nav-num">HOW</span>Study Methodology</a></li>
          <li><a href="../gnums/accounting/scope.html"><span class="nav-num">ACC</span>Accounting &mdash; Scope</a></li>
          <li><a href="../gnums/staff/scope.html"><span class="nav-num">STF</span>Staff &mdash; Scope</a></li>
          <li><a href="../gnums/hr-payroll/scope.html"><span class="nav-num">HRP</span>HR-Payroll &mdash; Scope</a></li>
          <li><a href="../gnums/exam/scope.html"><span class="nav-num">EXM</span>Exam &mdash; Scope</a></li>
          <li><a href="../gnums/exam/strategy.html"><span class="nav-num">PLAY</span>Exam &mdash; Strategy</a></li>
          <li><a href="../gnums/student/scope.html"><span class="nav-num">STU</span>Student &mdash; Scope</a></li>
          <li><a href="../gnums/student/strategy.html"><span class="nav-num">SPL</span>Student &mdash; Strategy</a></li>
          <li><a href="../gnums/student/cluster-01-core-identity.html"><span class="nav-num">SC1</span>Student / Core Identity</a></li>
          <li><a href="../gnums/student/cluster-02-subordinate-entities.html"><span class="nav-num">SC2</span>Student / Subordinate Entities</a></li>
          <li><a href="../gnums/student/cluster-03-master-config.html"><span class="nav-num">SC3</span>Student / Master &amp; Config</a></li>
          <li><a href="../gnums/student/cluster-04-certificate-workflow.html"><span class="nav-num">SC4</span>Student / Certificate Workflow</a></li>
          <li><a href="../gnums/student/cluster-05-bvm-activities.html"><span class="nav-num">SC5</span>Student / NCC NSS Yoga</a></li>
          <li><a href="../gnums/student/cluster-06-mentoring.html"><span class="nav-num">SC6</span>Student / Mentoring</a></li>
        </ul>
      </div>
    </nav>
  </aside>

  <main>
    <span class="eyebrow">02 · Design</span>
    <h1>Architecture</h1>
    <p class="lede">
      A request flows through model-binding validation, an application service that resolves the
      client-specific strategy, and finally domain code. No mediator, no command bus.
    </p>

    <div class="callout">
      <strong>Tenancy note:</strong> "tenant" throughout this page refers to a <em>client</em>.
      Each client owns its Postgres DB. Tables like <code>FEATURE_FLOW_BINDING</code> shown below
      live inside each client's DB; there is no shared multi-tenant store. See
      <a href="10-tenancy-model.html">10 · Tenancy Model</a> for the concrete isolation design.
    </div>

    <h2>Request pipeline</h2>
    <div class="mermaid">
graph TD
    A[HTTP Request] --> B[ASP.NET Core Controller]
    B --> C[Model Binding + FluentValidation auto-validation]
    C -->|fail| F[400 ProblemDetails]
    C -->|pass| D[Application Service]
    D --> E[IFeatureFlowResolver]
    E --> H{Resolve Strategy}
    H -->|Tenant A v2| I1[FeatureFlow_A_v2]
    H -->|Tenant B v1| I2[FeatureFlow_B_v1]
    H -->|Default| I3[FeatureFlow_Default]
    I1 --> J[Strategy.ValidateSemantic]
    I2 --> J
    I3 --> J
    J --> K[Rule Engine evaluates UI-defined rules]
    K -->|fail| F
    K -->|pass| L[Domain Aggregate enforces invariants]
    L --> M[Repository persist + events]
    M --> N[200 OK + Result]
    </div>

    <h2>Component responsibilities</h2>
    <table>
      <thead><tr><th>Component</th><th>Owns</th><th>Does <em>not</em> own</th></tr></thead>
      <tbody>
        <tr>
          <td>FluentValidation</td>
          <td>Shape, format, ranges, required-by-default</td>
          <td>Tenant logic, workflow, domain rules</td>
        </tr>
        <tr>
          <td>Application Service</td>
          <td>Orchestrate: resolve strategy, run it, map result to HTTP</td>
          <td>Business rules, persistence details</td>
        </tr>
        <tr>
          <td>TenantFlowResolver</td>
          <td>Map <em>(tenant, feature, version)</em> → strategy instance</td>
          <td>Validation rules, persistence</td>
        </tr>
        <tr>
          <td>FeatureFlow strategy</td>
          <td>Semantic checks + workflow orchestration</td>
          <td>Shape checks (delegated), invariants</td>
        </tr>
        <tr>
          <td>Rule engine</td>
          <td>Evaluate JSON rules persisted from admin UI</td>
          <td>Static rules known at compile time</td>
        </tr>
        <tr>
          <td>Domain aggregate</td>
          <td>Invariants that must always hold</td>
          <td>Tenant-specific behavior</td>
        </tr>
      </tbody>
    </table>

    <h2>Configuration storage</h2>
    <p>
      These tables live <strong>inside each client's Postgres database</strong> (see
      <a href="10-tenancy-model.html">page 10</a>). There is no <code>ClientId</code> column — the
      database itself is the discriminator. The client registry lives in the central
      <code>PlatformControl</code> DB.
    </p>
    <div class="mermaid">
erDiagram
    FeatureFlowBinding }o--|| FeatureFlowVersion : points_to
    FeatureFlowVersion ||--o{ RuleSet : contains
    RuleSet ||--o{ Rule : contains

    FeatureFlowBinding {
        string FeatureKey PK
        uuid FlowVersionId FK
        timestamptz EffectiveFrom
    }
    FeatureFlowVersion {
        uuid Id PK
        string FeatureKey
        int Version
        string StrategyKey
    }
    RuleSet {
        uuid Id PK
        uuid FlowVersionId FK
        string Name
    }
    Rule {
        uuid Id PK
        uuid RuleSetId FK
        string FieldPath
        string Operator
        jsonb ValueJson
        string Code
        string Message
        string Kind
    }
    </div>

    <h2>Resolution order</h2>
    <p>For request <code>(feature=F)</code> within the current client's DB context:</p>
    <ol>
      <li>Look up <code>FeatureFlowBinding</code> where <code>FeatureKey=F AND EffectiveFrom &lt;= now()</code>. Latest wins.</li>
      <li>If no binding, fall back to the <code>default</code> strategy for feature <code>F</code>.</li>
      <li>Strategy class is instantiated via DI keyed registration using <code>StrategyKey</code>.</li>
      <li>Strategy loads its <code>RuleSet</code> rows lazily, cached per flow version (within the client's request scope).</li>
    </ol>

    <h2>Caching</h2>
    <ul>
      <li><strong>Flow bindings:</strong> in-memory, 5-minute TTL, busted on admin save (publish <code>FlowBindingChanged</code> event).</li>
      <li><strong>Rule sets:</strong> keyed by <code>(FlowVersionId, RuleSetName)</code>; immutable per version, evicted only when the version is superseded.</li>
    </ul>

    <h2>Versioning</h2>
    <ul>
      <li>A new flow version is a <em>new row</em> in <code>FEATURE_FLOW_VERSION</code>, never an in-place mutation.</li>
      <li>The binding switch is the deployment unit. The admin UI changes the binding, not the rules of an active version.</li>
      <li>Rollback is achieved by repointing the binding to a prior version row.</li>
    </ul>

    <div class="doc-footer">
      <a href="01-findings.html">
        <span class="label">← Previous</span>
        <span class="title">01 · Findings</span>
      </a>
      <a href="03-code-sketch.html" class="next">
        <span class="label">Next</span>
        <span class="title">03 · Code Sketch →</span>
      </a>
    </div>
  </main>
</div>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>mermaid.initialize({ startOnLoad: true, theme: 'default' });</script>
</body>
</html>