Skip to main content
The Vexa runtime is modeled as code using FINOS CALM (Common Architecture Language Model). There is one chart — the repo-root architecture.calm.json — the single source of truth; calm/ holds the governance controls and the reusable pattern that validate it. Two CI gates keep it honest: pnpm gate:calm (FINOS pattern conformance) and pnpm gate:dataflow (model↔disk completeness, ownership enforcement, and a reality diff against the code) — so the architecture description can’t silently drift from the system.

​
What’s modeled

The chart carries both lenses at once: the complete module / service / contract inventory (every core/* service, module, and sealed contract is registered — adding one without registering it turns CI red) and the runtime / data-flow view: the standing services (gateway, meeting-api, agent-api, admin-api, runtime), the runtime-spawned workers (bot, agent-worker — deployed-in the runtime kernel), the redis transcript fabric, the durable stores (postgres, object storage), and the first-party, self-hostable STT boundary.

​
Controls (governance, machine-checked)

The model carries governance controls, each backed by a JSON-Schema requirement in calm/controls/:
  • single-writer (P23) — every data carrier declares exactly one producer; readers never re-derive a producer’s data.
  • render-only — the terminal renders transcript and cards; it never re-derives or republishes.
  • data-egress — the bot → transcription edge declares its egress posture. Default is tenant-hosted, so meeting audio need not leave the tenant.

​
The pattern

calm/patterns/meeting-intelligence.pattern.json is a reusable CALM pattern a meeting-intelligence deployment must conform to: a single authenticated edge, a capture worker, a collector, a copilot, a render-only client, and a declared STT egress boundary. Conformance is fail-closed — a design that omits the egress control or the render-only client is rejected:
Because the model is standard CALM, you can also calm generate a conformant starter architecture from the pattern and validate your own deployment against it with the FINOS calm-cli.

​
Generated views

Diagram views are carved from the chart, never drawn by hand. pnpm arch:dsl --write regenerates docs/views/ deterministically, and gate:dataflow fails when they are stale: The chart is also sealed (architecture.seal.json): any edit fails CI until deliberately re-sealed with pnpm seal:arch, so ownership or boundary changes are always a reviewed act.

​
Why this exists

A standard, validated model gives one diffable source of truth for the architecture, makes the single-writer and trust-boundary invariants machine-checkable, and lets the design be consumed by any CALM tooling — not a bespoke diagram that rots.