Phase C — Application Architecture
The application components that realise the capabilities, the interfaces between them, and the two sequences that matter most: a generation run, and a runtime request with authorization compiled in.
C5 · Application component & communication diagramComponents by layer, with the interfaces that connect them
Four layers plus cross-cutting services. Blue edges are the generation path; pink edges are the runtime path; teal dashed edges are metadata flows. The only component permitted to touch production data is the query compiler, through the supergraph gateway.
generation pathruntime pathmetadata / policy flow
C6 · Application interaction matrixProducer → consumer, and the interface between them
| From | To | Interface | Style | Contract / notes |
|---|---|---|---|---|
| Requester portal | Intake service | submitRequest · answerClarification | GraphQL (platform's own) | Returns UseCaseSpec or a clarifying question; run id for tracking |
| Intake service | Supervisor | spec.valid / spec.ambiguous | typed event | Zod-validated; the supervisor rejects anything else |
| Supervisor | Scout · Composers · Verifier | run step (budget, inputs) | typed command + event reply | Every reply is a typed artifact; prose cannot advance the machine |
| Scout | Catalog service | search · expandJoins · getCard | internal API (read-only) | Pre-filtered by the spec's actors' entitlements; returns cards + join paths with ids |
| Composers | Policy service | lookup(classification → policy) | internal API (read-only) | Policies applied to every classified field; verifier re-checks independently |
| Composers | Schema registry | compose(dryRun) | registry API | Composition errors returned to the composer as a typed report |
| Verifier | Sandbox runner | runGolden · scanPII · buildComponent | job API | Sample DB only; component builds use a locked dependency allow-list |
| Verifier | Schema registry · Policy service | composition check · policy coverage | registry / internal API | Deterministic; report attached to the run |
| Agents | LLM gateway | complete(templateVersion, model tier, budget) | internal API | Tier resolves to a pinned deployment; usage attributed to the run |
| Supervisor | Review workspace | review bundle (spec, subgraph, diff, reports, preview) | artifact store + UI | Decision returned as an approved / rejected event with reviewer identity |
| Supervisor | Schema registry | publish(slice, ops, spec, releaseUnit) | registry API | Only reachable after the approval event; write paths need their own approval |
| Schema registry | Supergraph gateway | supergraph SDL · persisted documents | pull / push on publish | Breaking-change detection blocks publish; last good version keeps serving |
| Business app shell | Edge gateway | opId + variables + bearer token | HTTPS (persisted operations) | No query text leaves the browser; unknown ids rejected at the gateway |
| Supergraph gateway | Query compiler | execute(op, args, claims) | federation subgraph call | Claims forwarded from the edge-validated token; never asserted by the caller |
| Query compiler | Policy service | predicates(role) · columnPolicies(slice) | internal API (cached) | Row-scope templates composed into SQL; denied columns nulled in projection |
| Query compiler | Response cache | get / set (op, args, entitlement fp, catalog generation) | cache API | Cannot serve across entitlement fingerprints; busts on drift |
| Query compiler | Systems of record | batched, scoped SQL | DB driver / replica | Read-only credentials; cost ceiling enforced with actual arguments |
| Supergraph gateway | Proposal service | proposal mutations | federation subgraph call | Creates a proposal; the owning system applies after its own approval |
| Crawler | Catalog service | upsert cards · joins · new version | internal API + event | Diff emitted on the event bus → re-verification of affected use cases |
| All components | Trace & telemetry | spans with use-case id, run id, op id | OpenTelemetry | Every compiled query logged with its predicate set |
C7 · Sequence · generation runFrom a prose request to a published slice and spec
Dashed arrows are replies. The supervisor is the only participant that talks to everyone — and it only accepts typed events.
C8 · Sequence · runtime requestA screen loads, and a proposal is raised — with entitlements compiled into the SQL
The browser sends an operation id, never a query. Claims come from the token the edge validated. The compiler is the only participant that shapes SQL, and it shapes it before execution.