# 05 — System architecture

**Status:** Draft. Written 2026-11-07. Decisions referenced: ADR-0001…0005.

The platform serves personal, internal-team, customer-facing and embedded-agent jobs
([product scope](20-product-scope.md)). Organizations are isolation and billing boundaries
for individuals as well as businesses. The WhatsApp sequence below is the first integration
slice; channel adapters and the API expose the shared runtime for other jobs. This scope
clarification does not change the runtime or tenancy contracts.

## 1. Context (C4 level 1)

```mermaid
flowchart TB
  Contact((Person: individual / coworker / customer\nWhatsApp / IG / Telegram / email / phone))
  Operator((Operator\norg member in dashboard))
  Dev((Developer\nSDK / REST / MCP))
  subgraph Charla
    Web[apps/web\nNext.js: dashboard, public API, webhook ingress]
    RT[apps/runtime\nMastra server: turn workers, tools, memory, schedules, evals]
    DB[(Postgres\npublic + mastra schemas)]
    RD[(Redis\nqueues, locks, rate limits)]
    OBJ[(Object store\nattachments, exports)]
  end
  Meta[Meta Graph API\nWhatsApp via BSP: Kapso / 360dialog\nInstagram, Messenger direct]
  TGm[Telegram Bot API]
  TW[Twilio / Telnyx\nSMS, voice]
  RS[Resend\nemail]
  LLM[Model providers\nAnthropic, OpenAI, Google, OpenRouter]
  STT[STT/TTS providers]
  PAY[Mercado Pago, Stripe]
  TenantAPI[Tenant systems\nwebhook tools, MCP servers, identity webhook]
  Contact <--> Meta & TGm & TW & RS
  Meta & TGm & TW & RS --> Web
  Web --> RD --> RT
  RT --> Meta & TGm & TW & RS
  RT <--> LLM & STT & PAY & TenantAPI
  Web & RT <--> DB & OBJ
  Operator --> Web
  Dev --> Web
```

## 2. Containers (C4 level 2)

| Container | Tech | Responsibilities | Scaling |
|---|---|---|---|
| **apps/web** | Next.js 16 App Router, React 19, Tailwind, shadcn/ui, next-intl, Better Auth (or Clerk) | Dashboard (RSC pages, server actions), public REST API (`/api/v1/*`), OpenAI/Anthropic-compatible endpoints, **channel webhook ingress** (`/webhooks/{whatsapp,instagram,messenger,telegram,twilio,resend}`), Embedded Signup callback, billing portal, docs site (`/docs/*.md` also served raw, `llms.txt`) | Stateless; Vercel or Node containers; horizontal |
| **apps/runtime** | Mastra 1.x server (Hono) built with `mastra build`; Node 22 LTS | Turn workers (durable jobs), tool execution (webhook/MCP/code), memory consolidation, schedules (alerts/loops), outbound delivery workers, eval runs, signals classification, webhook dispatcher (outbound events), Mastra MCP server | Containers (Railway / Fly.io / Render / AWS ECS) in the data region; scale workers by queue depth |
| **Jobs** | Mastra harness (durable evented agents, signals, background tasks, schedules) for turns; **BullMQ** on Redis for `steer`, `deliver`, `webhook-out`, `media`, `maintenance` | Durable turn execution with recovery, per-thread ownership, debounce, retries with backoff, cron | Inside `apps/runtime` replicas; Inngest is the documented escape hatch |
| **Postgres** | Neon or Supabase or RDS; pgvector | Control-plane schema (`public`), Mastra storage (`mastra`), vectors for semantic recall | Primary + read replica later; region per data-residency choice |
| **Redis** | Upstash or managed Redis | Steering buffers, turn locks, abort flags, provider rate limiters, idempotency caches, PubSub for memory consolidation | Small |
| **Object store** | Cloudflare R2 or S3 | Inbound/outbound media (90-day default retention), exports, eval artifacts | — |
| **Observability** | OpenTelemetry → Mastra observability store (Postgres, later ClickHouse); exporters to Braintrust/Axiom/OTLP per org | Traces, spans, logs, metrics | — |

## 3. Components inside `apps/runtime` (C4 level 3)

```mermaid
flowchart LR
  subgraph runtime
    JQ[BullMQ workers\nsteer, deliver, webhook-out, media, maintenance]
    ST[Steering\nbuffer, debounce, batch, abort]
    TBld[Turn builder\nagent version, history, principal, action state, channel caps, window state]
    AR[AgentRuntime port\nMastra impl: agent factory, processors, memory scopes]
    TD[Tool dispatcher\nscopes, approval policy, preview/freshness, MCP toolsets, webhook signer, sandbox]
    GA[Governed actions service]
    DL[Delivery service\nrender per channel, template vs free-form, idempotency, receipts]
    MEM[Memory consolidation\nobservational memory worker]
    SCH[Scheduler\nalerts, loops, retention prune]
    EV[Evals runner, signals classifier, replay]
    WH[Outbound webhook dispatcher\nHMAC, retries 72h]
    MCP[MCP server\n/api/mcp]
  end
  JQ --> ST --> TBld --> AR --> TD --> GA
  AR --> DL
  JQ --> SCH --> AR
  JQ --> EV
  GA --> WH
  DL --> WH
```

Composition (T-187, [ADR-0016](adr/0016-feature-composition-roots.md)): each component above is
built by its feature's `wire.ts` (`apps/runtime/src/<feature>/wire.ts`), which receives the shared
infrastructure (`RuntimeInfra` in `src/wiring.ts`: database, Redis, Mastra storage, models,
object store, secrets, logger) and the services of other features it needs, and returns its own.
`src/mastra/index.ts` builds the infrastructure and the Mastra instance, calls each `wire*` in a
fixed order and attaches the shutdown (`runtimeShutdownPlan`, `runtimeReleasePlan` in
`src/lifecycle/shutdown.ts`). `apps/web` does the same: `src/server/<feature>/wire.ts` on
`src/server/infra.ts`, re-exported by `src/server/deps.ts`.

## 4. Key request flows

### 4.1 Inbound WhatsApp message → reply

```mermaid
sequenceDiagram
  participant M as BSP (Kapso) forwarding Meta Cloud API
  participant W as apps/web /webhooks/whatsapp/:provider
  participant Q as BullMQ steer queue
  participant R as apps/runtime (Mastra durable agent)
  participant L as Model provider
  participant T as Tenant tool (webhook/MCP)
  M->>W: POST webhook (provider signature)
  W->>W: verify provider signature, parse, idempotency on wamid
  W->>W: upsert contact, conversation; insert inbound_events + messages
  W->>W: consent keyword check (BAJA/STOP…) → consent event, no turn
  W->>Q: push to steer buffer; upsert delayed steer job (jobId = conversation_id)
  W-->>M: 200 within < 1 s
  Q->>R: steer job: pop batch after debounceWindow or maxBatch; run media pipeline
  R->>R: agent.sendMessage(batch, thread): harness starts a run or delivers into the active one
  R->>R: build TurnInput (agent version, history, principal via identity webhook cache, action state, window state)
  R->>L: stream model (Mastra Agent with processors + memory)
  L-->>R: tool call
  R->>R: policy check (scopes, approval) → run / propose action
  R->>T: signed tool call (HMAC, turn context)
  T-->>R: result
  R->>L: continue
  L-->>R: text
  R->>R: render for WhatsApp (text / interactive), check 24h window
  R->>M: POST /messages (idempotent)
  M-->>R: message id; later status webhooks → receipts
  R->>R: persist outbound message, usage, trace; release lock; drain queued arrivals
```

### 4.2 Governed action (approval before a write)

1. Model calls `preview_x` (inline, scope-checked) then `write_x` (policy `approval: ask`).
2. Dispatcher canonicalises args (sorted keys, drop `undefined`, exclude `descriptionArg`),
   hashes, verifies a matching preview within 24 h, runs optional preflight, **persists
   `actions` row** (`pending`), renders the approval summary (blocks schema) as a WhatsApp
   interactive message with Approve/Decline reply buttons (or Flow when `approvalProof:
   verified`), returns `approval_requested` to the model. Agent says one sentence and stops.
3. Decision arrives as a button reply (`interactive.button_reply.id = act_<id>:approve`), words
   (`action_respond` tool), dashboard, Slack, or Flow `nfm_reply`. Dispatcher checks approver
   scopes, re-runs preview if `freshnessFields`, supersedes on diff, else executes the **stored
   call** with `context.approval`, moves to `completed | failed`, updates the message, fires
   `action.<status>` webhook, and gives the agent a turn with the result.

### 4.3 Partner deployment (SaaS creates an agent per customer)

Each customer of the partner is its own client org, linked to the partner in
`registry.partner_links` (ADR-0012). `POST /api/v1/developer/deployments` with `external_ref` →
resolve or create the client org and its link → inside `withOrg(clientOrgId)`, create/update agent from template or
spec → attach channels (WhatsApp via Embedded Signup link when credentials are not supplied;
Telegram with bot token; `api`) → store identity and actions webhooks → respond with per-channel
status (`connected | needs_action | error | skipped`) and `missingSecrets`.

### 4.4 Connecting a WhatsApp number through the BSP (tenant keeps its own WABA)

1. `apps/web` creates (or reuses) a BSP customer/tenant record for the org via the provider API
   and asks for an onboarding link (Kapso: Embedded Signup hosted under Kapso's Meta app;
   360dialog: Integrated Onboarding link).
2. The dashboard opens the link in a popup; the tenant signs in to Meta, selects or creates its
   WABA and phone number, and chooses the Meta billing mode (pay Meta directly or use our
   managed credits).
3. The BSP calls our provider webhook when the number is connected; we store the provider's
   channel id and credentials encrypted, point the BSP webhook for that number at
   `/webhooks/whatsapp/:provider`, fetch templates and quality rating.
4. A `channel_identities` row is created (`type: whatsapp`, `provider`, `waba_id`,
   `phone_number_id`). Nothing downstream depends on the provider.

### 4.5 External harness (tenant runs the loop)

Ingress and steering are identical. Instead of calling the Mastra agent, the turn worker POSTs a
signed `charla.turn` payload to the tenant's `dispatchUrl` (push) or exposes it on
`/api/v1/harness/inbox/next` (inbox). The tenant replies through the turn-scoped API
(`/api/v1/turns/:turnId/messages|stream|actions|attachments|typing|lease|arrivals|complete`)
with a short-lived turn token. Delivery, receipts, history and traces stay ours.

### 4.6 Scheduled alert / loop

One Mastra workflow schedule per alert (cron in the alert's IANA zone) starts the
`alert-dispatch` workflow on the single scheduler replica (T-082). The workflow iterates the
alert's subscribers: `shouldSend` over their preferences, dedupe on
`<alert>:<subscriber's local date>` in `alert_deliveries`, then a silent notice turn
(`sendSignal`, `ifIdle: wake`, `trigger: alert`) on the contact's conversation. If the 24 h
window is closed on WhatsApp, `deliver` sends the reply through the alert's **utility template**
(the text in its last variable); without one the subscriber is skipped. Otherwise free-form.
Mastra does not replay fires missed while no scheduler ran; the next tick fires as usual.

A **follow-up** an agent schedules for one contact (`schedule_followup`, #636) uses the same
single scheduler: one schedule per follow-up (cron of its minute in the org's zone) starts the
`followup-dispatch` workflow, which claims the row (`scheduled → fired`), sends a silent notice
turn with `turns.followup_id` under the `followup-fire:<id>` key and deletes the schedule;
`deliver` marks it `delivered` or `held`. A one-off fire whose time passed while no scheduler
ran is still due, so the next scheduler's first tick fires it ([06](06-domain-model.md) §2.8).

## 5. Cross-cutting concerns

| Concern | Approach |
|---|---|
| **Tenancy** | `org_id` on every tenant table; Postgres RLS with `SET LOCAL app.org_id`; service role only in workers with explicit org context; Mastra `resource`/`thread` ids carry org prefix |
| **Idempotency** | Inbound: provider message id unique per channel identity. Outbound: `idempotency_key` per send, stored with provider message id; replay returns same result. Jobs: step memoization in runner. |
| **Ordering** | One running turn per conversation = one durable-agent claim per thread (5 s renew, 15 s lease, Postgres fencing); steer jobs deduplicated by conversation id; outbound sends serialized per conversation in the `deliver` queue |
| **Cancellation** | Redis abort flag per turn; `AbortSignal` passed to Mastra stream; checked between steps and before each send |
| **Secrets** | AES-256-GCM envelope encryption (KMS-managed data key); `{{SECRET}}` substitution host-side; never in prompts, traces or tool args; redaction processor on outputs |
| **Outbound URL safety** | Public HTTPS only; DNS resolved and checked against private ranges; no redirects; per-tool timeouts |
| **Signing** | HMAC-SHA256 `Charla-Signature: t=<ts>,v1=<hex>` over `"<ts>.<raw-body>"`, 5-minute tolerance, 24 h overlap on rotation; Ed25519 JWKS for harness dispatch (Later) |
| **Observability** | One trace per turn (`turn_id = trace_id`); spans `llm.step.<n>`, `tool:<name>`, `delivery:<channel>`, `memory.recall`, `identity.resolve`; named stop reasons |
| **Localisation** | Agent `locale` drives default prompt language, date/number formatting, consent keyword set, template language code; dashboard in es, pt-BR, en |
| **Data residency** | Org `region` chosen at creation: `us`, `eu`, `br` (all three at GA, `docs/13` §4.3). Each region = its own Postgres + Redis + object store + runtime; `apps/web` is global and routes by org through `RegionRouter` and a global registry that holds only `org → region` and `provider account → region` next to auth ([15](15-infrastructure-devops.md) §9, ADR-0010) |

## 6. Technology choices summary

| Area | Choice | Alternatives considered |
|---|---|---|
| Web framework | Next.js 16 App Router | Laravel (evaluated and rejected, [04](04-stack-decision.md) §4) |
| Agent runtime | Mastra 1.x | LangGraph.js (runtime alternative behind the `AgentRuntime` port, ADR-0005) |
| ORM / migrations | Drizzle ORM + drizzle-kit | Prisma |
| Turn execution | Mastra harness: durable evented agents + signals + background tasks + schedules | Trigger.dev (first draft), Inngest via `createInngestAgent` (escape hatch) |
| Queues | BullMQ on Redis (`steer`, `deliver`, `webhook-out`, `media`, `maintenance`) | Inngest functions |
| WhatsApp BSP | Kapso (primary), 360dialog (EU-hosted alternative) | Twilio WhatsApp, direct Meta Tech Provider (Phase 3+) |
| Auth | Better Auth + organizations plugin | Clerk (if SAML needed early) |
| Validation | Zod (shared with Mastra tool schemas) | Effect Schema (Keiki uses Effect) |
| API docs | OpenAPI 3.1 generated from Zod (zod-openapi), served at `/openapi.json` | — |
| UI | shadcn/ui, Tailwind v4, Radix | — |
| i18n | next-intl | — |
| Email | Resend (outbound + inbound) | AgentMail |
| STT | Decided by benchmark ([16-testing-strategy.md](16-testing-strategy.md)); pending, dataset not recorded ([stt-benchmark.md](research/stt-benchmark.md) §5) | Whisper, Deepgram, ElevenLabs, AssemblyAI |
| Sandbox | E2B (Later) | Vercel Sandbox, Daytona |
| Browser | Browserbase + Stagehand (Later) | — |
| Payments by agents | Mercado Pago (OAuth) + Stripe Connect (Accounts v2), direct charges, no fee, behind `PaymentProvider` ([ADR-0019](adr/0019-agent-payments.md)) | dLocal for Tier B (#434), EBANX |
| Appointments in the business's calendar | Google Calendar (OAuth) behind `CalendarProvider`; Charla owns availability, the template's tools run as `calendar` tools ([ADR-0020](adr/0020-calendar-appointments.md)) | Microsoft 365, Cal.com |
| Hosting | Vercel (web) + Railway/Fly/Render (runtime) + Neon/Supabase (DB) + Upstash (Redis) + R2 (objects) | AWS end-to-end |
