Architecture

The Platform is the dynamic (runtime‑interpreter) mode of the UIKit stack: instead of the CLI generating a static app at build time, a frontend fetches a tenant's app.json from the engine and renders it live. The same app.json schema serves both modes.

Request flow

                         ┌──────────────────────────────────────────┐
  English prompt ───────▶│  @samabaasi/ai                            │
                         │   NL → app.json (validate-and-retry)      │
                         │   governed agent (tool calls, gated)      │
                         └───────────────┬──────────────────────────┘
                                         │ proposes (never applies)
                                         ▼
  Author edits ─────────▶ @samabaasi/core  (app.json schema, Zod) ◀── single source of truth
                                         │ validated
                                         ▼
                         ┌──────────────────────────────────────────┐
  Browser ◀── renders ───│  @samabaasi/renderer (DynamicRenderer)   │
                         └───────────────┬──────────────────────────┘
                                         │ fetch GET/PUT /api/app-json
                                         ▼
                         ┌──────────────────────────────────────────┐
  OData changes ────────▶│  @samabaasi/engine                        │
                         │   multi-tenant store + auth + vault       │
                         │   workflow engine (detect→run→approve)    │
                         └──────────────────────────────────────────┘
                                         │ binds
                                         ▼
                              @samabaasi/uikit + OData service

Layers (MVP split, inherited from the library)

• Model — the OData client/query builder (in the library) + the engine's stores/vault.
• Presenter — the renderer's data binding (useODataSource) + the workflow/agent runtimes.
• View — UIKit components, instantiated by the renderer from app.json sections.

Pluggable interfaces (the "in‑memory now, Postgres at deploy" seam)

Everything stateful is behind an interface with a tested in‑memory implementation and a deploy adapter, validated by a shared contract suite:

Interface	Dev	Deploy
TenantAppJsonStore	in‑memory	Postgres/Prisma
CredentialVault	in‑memory (AES‑256‑GCM)	Postgres (same crypto)
Job queue	in‑memory + tick()	pg‑boss worker
ChangeDetector	snapshot+hash poll	same, scheduled (per the OData service's capabilities)
LlmClient	mock (tests)	Claude

This is why the platform is fully testable offline yet deployable without rewrites — see Deployment.

Design rules

• app.json is data, never code. The AI and authors produce configuration; only code we wrote interprets it.
• The model proposes, the platform disposes. Every AI tool call is gated, approved (for writes), and audited — see AI & the governed agent.
• One schema everywhere. @samabaasi/core validates the renderer's input, the engine's writes, and the AI's output.