> ## Documentation Index
> Fetch the complete documentation index at: https://rapidreview.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> How the pieces connect and what each one owns — for operators and contributors.
## Topology
Every agent client talks to one brain over `POST /mcp` (Streamable HTTP, JSON-RPC). The browser UI talks to the same brain over `/api/…`. There is no local proxy on agent machines. Byte transfers — artifact, storage, and feed uploads, sandbox output pulls — happen agent-side over presigned or token URLs, so the brain never receives a checkout root and never serves live checkout files.
## The brain, by layer
| Layer | Owns |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Research Core** | States, transitions, gates, attempts, and transaction invariants for the experiment and reflection workflows — declared as data (`experiment_workflow.py`, `reflection_workflow.py`) and validated at import time |
| **Artifacts** | Submitted evidence and immutable sealing |
| **Application** | Combines research facts with sandbox, feed, and storage modules to produce `workflow.status_and_next` guidance |
| **Surface** | Authentication, authorization, MCP/HTTP schemas (`TOOL_MANIFEST`), response presentation |
| **Sandbox** | Provider-neutral `SandboxBackend` port; registry-driven drivers (VM over management SSH, Modal as managed container); reaper and observation |
| **Feed, Literature, Storage** | Voices/posts/attachments; living review and papers ledger; heavy-object ledger with leases |
| **Skills** | Tell agents how to do the work; they never define legal transitions |
## State and storage
| Store | Local mode | Control mode |
| --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Records | SQLite | Postgres (`MERV_DB_URL`); startup migrations under a session advisory lock derived from the full DSN |
| Submitted bytes | Local directory | S3-compatible blob bucket (MinIO in the reference stack) |
| Heavy objects | optional | optional S3 (`MERV_STORAGE_PROVIDER=s3`) |
| Secrets | none | Supabase auth pair, management SSH key, provider credentials, `MERV_WAIT_SECRET`, `MERV_ADMIN_TOKEN` — in the deployment's secret store, never sent to clients |
## Auth and tenancy
One `Authorization: Bearer` header; three credential shapes dispatched by prefix — session JWT, `rr_sk_`, `mk_` — plus OAuth (DCR + PKCE) for interactive MCP clients. Project membership is the tenant boundary, enforced at the HTTP path gate and the MCP funnel. Local mode is auth-free. Details: [Configure auth](/docs/merv/self-host/configure-auth).
## Sandboxes
The brain provisions, leases, observes, and terminates; the agent holds the SSH key and runs commands. Every VM gets the same bootstrap (caller key + management key, `rec.sh` transcript wrapper, `merv_run`, then the ML toolchain). Ids are `:` so operations route to the owning driver.
## Distribution
Canonical content lives in `merv/` (`skills/`, `agents/`, `bin/`, adapters under `clients/`). CI publishes a generated `merv-client` branch and a `merv-hermes-client` repo after every change on `main`; marketplace manifests on `main` serve Codex, Claude Code, Copilot CLI, and Cursor; the runner is a backend-free zipapp at `rapidreview.io/merv/runner/`.
Deeper: `merv/docs/ARCHITECTURE.md` and `merv/docs/MODULE_BOUNDARIES.md` in the repository.