Phase D — Technology Architecture

The platform stack (TypeScript end-to-end), the environments and what each is allowed to hold, a reference cloud deployment with a local-first equivalent, and the technology standards catalog with cost notes.

← C appNext: E/F →

D1 · Platform decompositionLayers and the technology that realises each

Presentationone React app, many specs

ViteReactTanStack Query & Tableurql (persisted operations)Module Federation (reviewed remotes)Spec renderer + component registryReview workspaceRequester portal

API & gatewayone supergraph, persisted documents only

Edge gateway (APIM / Front Door + WAF)Hive Gateway / Apollo Router-class supergraph gatewayGraphQL Yoga subgraphs (federation v2)GraphQL Hive schema registry (self-hosted)Persisted document store

Generationtyped agents, deterministic supervisor

Node.js / TypeScript servicesXState supervisorZod-typed agent outputsLLM gateway (Azure OpenAI · Anthropic Claude; pinned)Prompt template registry (versioned)Archetype librarySandbox workers (component build · lint · screenshot)

Knowledge & policythe RAG substrate

PostgreSQL + pgvectorPostgres full-text rankingJoin-graph adjacency tablesCrawler (information_schema · comments · profiles · query logs)Policy store (classification · entitlement templates)Azure AI Search adapter (enterprise option)

Datasystems of record and the platform's own

PostgreSQL systems of record (scaled public sample ≥3,000 tables)Read replicasSample sandbox database (synthetic)Redis response cache (entitlement-fingerprinted)Kysely query compilerArtifact / blob store

Verification & deliverygates in CI, not in a wiki

Composition checks (registry) in CIPolicy-coverage walkerGolden test runnerPII scannerAccessibility lint (spec)Containers (Docker)IaC (Bicep / Terraform)GitHub Actions

Security & observabilitycross-cutting

OIDC identity (Entra ID) · claimsKey Vault / secretsWAF · rate limitingOpenTelemetryTrace store (per use case, per run)Azure Monitor / App InsightsCost attribution per use case

D2 · Environments & locationsWhere each component runs, and which data classes each environment may hold

The data rule is the environment rule: generation and verification never run where production data lives; production runs nothing that generates.

Development

Local-first, Docker Compose.

Runs
  • All services, single node
  • Scaled sample DB (synthetic)
  • Hive registry container
  • Any LLM provider (pinned)
Data allowed

Synthetic only.

Purpose

Build the reference implementation; run every gate locally.

Sandbox (generation)

Where agents and gates run.

Runs
  • Intake · supervisor · Scout · composers · verifier
  • Sandbox runner (golden tests, PII scan, component builds)
  • Catalog + policy services
  • Sample sandbox DB
Data allowed

Catalog metadata, masked profiles, synthetic sample data. No production rows.

Purpose

Produce and verify artifacts.

Staging (review & preview)

Where humans look before publish.

Runs
  • Review workspace
  • Preview runtime against the sample sandbox
  • Registry (candidate versions)
Data allowed

Synthetic sample data; candidate artifacts.

Purpose

Approve release units; rehearse composition.

Production (runtime)

Where business users are served.

Runs
  • Edge gateway · supergraph gateway
  • Query compiler · proposal subgraph
  • Spec runtime (static) · component remotes
  • Response cache · trace store
  • Crawler (metadata read only)
Data allowed

Production data via compiled, scoped SQL only.

Purpose

Serve approved release units; emit drift events.

D3 · Networked computing / deployment diagramReference Azure deployment — with the local-first equivalent underneath

Business usersbrowser · OIDC session Static Web Appspec runtime bundlecomponent remotes (CDN) Front Door + WAFTLS · global entry APIM (edge)JWT · rate limits AZURE CONTAINER APPS ENVIRONMENT · PRIVATE VNET Supergraph gatewaypersisted docs · claims forward Compiler subgraphKysely · predicates Proposal subgraph→ owning systems' queues Schema registry (Hive)composition · versions · persisted docs Intake + SupervisorXState · durable run log Scout + Composerstyped outputs (Zod) Verifiernine gates Sandbox runner (jobs)golden · PII · component builds Crawler (job)schedule + DDL events LLM gatewaypinned deployments · budgets Event workersdrift → re-verify · degrade Portal + review APIsrequester · reviewer workspaces Systems of recordcustomer VNet · private link · read replicasreference impl: Postgres, scaled sample ≥3,000 tables Postgres Flexible Servercatalog (pgvector + FTS + join graph)platform DB (runs, specs, release units) Azure Cache for Redisresponse cache keyed byentitlement fingerprint Blob Storageartifacts · reportsscreenshots Sample sandbox Postgressynthetic data, same schemanever production rows Entra ID (OIDC)users · reviewers · service identities · claims Model endpoints (private endpoint)Azure OpenAI · Anthropic · pinned versions Event Grid / BusDDL · drift · publish Key Vaultsecrets · read-only creds Monitor + App InsightsOpenTelemetry · cost per use case Local-first equivalent (Docker Compose)Postgres + pgvector (SoR + catalog + sandbox) · Redis · MinIO (artifacts) · Hive registry container · any model provider behind the same gateway interface (pinned) · OTel collector + Grafana · Caddy as edge. Same gates, same code, same release unit. load app opId + token → claims supergraph SDL + persisted documents private link · scoped SQL cache catalog metadata · DDL golden tests model calls private endpoint

D4 · Technology standards catalogChoices, version policy, alternatives, and what drives cost

ConcernStandard / choiceVersion policyAlternatives consideredCost driver & control
Language & runtimeTypeScript end-to-end on Node.jsLTS Node; strict TS; single toolchain.NET/HotChocolate stack (production-proven elsewhere); Python agentsOne toolchain lowers build/ops cost; skills readily available
Agent orchestrationXState supervisor + typed agents (Zod)State machine definitions versioned with the release unitLangGraph.js; agent frameworksBudgets enforced in the machine: steps, tokens, wall-clock, cost per run
LLM accessLLM gateway; Azure OpenAI and Anthropic Claude behind one interfacePinned deployments; upgrade = a dated releaseDirect SDK calls per serviceModel spend per use case attributed by run id; small models for intake, larger for composition
Catalog storePostgreSQL + pgvector + full-text + adjacency tablesCatalog schema versioned; embeddings re-run only on changed cardsAzure AI Search (adapter provided); dedicated vector DBEmbeddings once per catalog version; cheap queries; scale-out by read replicas
GraphQLFederation v2 subgraphs (Yoga); Hive registry + gateway; persisted documentsComposition in CI; breaking-change detection blocks publishApollo Router/Studio; schema stitchingGateway compute is flat; per-slice composition keeps CI seconds-long
Query compilationCustom compiler on KyselyCompiler version part of the release unitHasura-style engines; ORM resolversCost ceilings with actual args; batching; entitlement-fingerprinted cache
Front endVite + React + TanStack + urql; Module Federation for reviewed remotesSpec DSL versioned; runtime supports N-1 spec versionsNext.js; generated apps per use caseStatic hosting; marginal cost of a screen is a JSON file
SandboxIsolated worker containers; locked dependency allow-list; synthetic DBAllow-list reviewed quarterlyServerless functionsEphemeral jobs; scale to zero
IdentityOIDC (Entra ID); claims validated at the edge; forwarded, never assertedClaim schema versioned with policyCustom authExisting tenant; no new cost
ObservabilityOpenTelemetry → Azure Monitor / App Insights (Grafana locally)Span attributes: use-case id, run id, op id, release unitVendor APMSampling on runtime traffic; full traces on generation runs
InfrastructureAzure Container Apps, Postgres Flexible Server, Redis, Blob, Key Vault, Event Grid/Service Bus; Bicep/Terraform; Docker Compose locallyIaC in repo; environments promoted by pipelineAKS (when scale demands); other clouds via containersScale-to-zero for generation; runtime sized by traffic; replicas for SoR reads
Systems of record (reference impl)PostgreSQL, public sample scaled to ≥3,000 tables with synthetic dataGenerator versioned; pathologies injected deliberatelySQL Server adapter nextContainers locally; Flexible Server in cloud