> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core.vexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture as Code (CALM)

> The runtime architecture is a validated FINOS CALM model — nodes, data carriers, single-writer ownership, and a self-hostable meeting-intelligence pattern, enforced in CI.

The vexa runtime is modeled as code using **[FINOS CALM](https://calm.finos.org/)** (Common Architecture
Language Model). The model lives in [`calm/`](https://github.com/Vexa-ai/vexa-core/tree/main/calm) and is
validated in CI by `pnpm gate:calm` — so the architecture description can't silently drift from the system.

## What's modeled

`calm/architecture.calm.json` is the runtime / data-flow view: the standing services
([gateway](/architecture/identity-and-trust), `meeting-api`, `agent-api`, `admin-api`,
[`runtime`](/architecture/execution)), the **runtime-spawned workers** (`bot`, `agent-worker` —
[`deployed-in` the runtime kernel](/architecture/execution)), the redis transcript fabric, the durable
stores (postgres, object storage), and the **first-party, self-hostable STT** boundary.

| Layer    | Nodes                                                                                     |
| -------- | ----------------------------------------------------------------------------------------- |
| Edge     | `gateway` — the one authenticated door (auth · routing · WS fan-out)                      |
| Services | `meeting-api` (collector hub) · `agent-api` (copilot) · `admin-api` (identity)            |
| Workers  | `bot` · `agent-worker` — ephemeral, spawned per meeting / per dispatch                    |
| Carriers | the redis [streams + pub/sub](/architecture/streaming) (transcript live + durable planes) |
| Stores   | postgres (transcripts · identity) · object storage (recordings)                           |
| STT      | `transcription` — first-party GPU service, **tenant-hosted by default**                   |

## Controls (governance, machine-checked)

The model carries [governance](/architecture/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:

```bash theme={null}
pnpm gate:calm
# = calm validate -p calm/patterns/meeting-intelligence.pattern.json -a calm/architecture.calm.json
```

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`](https://www.npmjs.com/package/@finos/calm-cli).

## Why this exists

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