> For the complete documentation index, see [llms.txt](https://docs.brain.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.brain.fi/architecture/system-overview.md).

# System Overview

Brain is a layered protocol where information flows up and control flows down. Each tenant has its own logical instance of every layer, with hard isolation at the database, credential-encryption, and policy boundaries.

### At a Glance

```
┌────────────────────────────────────────────────────────────────┐
│                    Clients (humans, agents)                    │
│   Dashboard · Internal services · External MCP · Surfaces      │
└────────────────────────────────────────────────────────────────┘
                              ↓ Auth (email/password · SIWX)
┌────────────────────────────────────────────────────────────────┐
│                          Brain API                             │
│              REST · JSON-RPC · MCP server surface              │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                  The Six-Layer Protocol Stack                  │
│  Raw → Ledger → Wiki → Policy → Agent → Audit                  │
└────────────────────────────────────────────────────────────────┘
                ↓                              ↓
┌─────────────────────────────┐  ┌─────────────────────────────┐
│        Off-chain state      │  │    On-chain commitments     │
│  Postgres · pgvector · Azure Blob   │  │   Base L2 · Brain contracts │
└─────────────────────────────┘  └─────────────────────────────┘
                                              ↓
                              ┌────────────────────────────────┐
                              │ Execution rails                │
                              │  Bank APIs · Processors ·      │
                              │  Session-key smart account     │
                              │  (x402 planned. RFC 0001)     │
                              └────────────────────────────────┘
```

### What Lives Where

| Component                     | Location                                 | Notes                                                                                          |
| ----------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Raw Artifacts**             | Azure Blob                               | Content-addressed, tenant-prefixed object storage                                              |
| **Ledger Records**            | Postgres                                 | Immutable, append-only with supersedence                                                       |
| **Wiki Graph and Embeddings** | Postgres + pgvector                      | Updated incrementally                                                                          |
| **Policy Compiled Form**      | Postgres                                 | Hash-anchored on-chain                                                                         |
| **Audit Hash Chain**          | Postgres                                 | Merkle roots batched on-chain                                                                  |
| **Agent Identity**            | `BrainMCPAgentRegistry` (Base L2)        | Stores `agentId`/`tenantId`/`scopeHash`/`behaviorHash` (ERC-8004 reputation planned. RFC 0001) |
| **Smart Account State**       | `BrainSmartAccount` per tenant (Base L2) | Session-key account (scope, spend caps, bound `policyVersion`)                                 |
| **Policy Hashes**             | `BrainPolicyRegistry` (Base L2)          | EIP-712 signed by tenant                                                                       |
| **Audit Anchors**             | `BrainAuditAnchor` (Base L2)             | EIP-712 signed by Brain anchorer                                                               |

### On-Chain Surface Is Intentionally Small

Brain's on-chain surface is intentionally minimal. **Most logic lives off-chain.** On-chain contracts exist for six narrow purposes:

| On-Chain Purpose                                         | Contract                  |
| -------------------------------------------------------- | ------------------------- |
| **Anchor State**                                         | `BrainAuditAnchor`        |
| **Register Policy Hashes**                               | `BrainPolicyRegistry`     |
| **Register Agent Identity**                              | `BrainMCPAgentRegistry`   |
| **Enforce Session-Key Scope/Limits and Route Execution** | `BrainSmartAccount`       |
| **Custody Conditional Escrow Locks**                     | `BrainEscrow`             |
| **Publish Reputation Roots**                             | `BrainReputationRegistry` |

All six contracts are deployed on Base Sepolia today and written in Solidity 0.8.x, built and tested with Foundry. Mainnet deployment is blocked on external audit, bytecode verification, and operator attestation. The contracts are immutable: there is no upgrade path in the MVP, and any change ships as a separately audited redeploy.

[**→ Smart contract overview**](/smart-contracts/overview.md)

### Six Layers, One API

The same API surface serves humans, internal agents, and external agents. Auth differs; primitives don't.

| Layer      | Primary API Endpoints                                    |
| ---------- | -------------------------------------------------------- |
| **Raw**    | `POST /v1/sources`, `POST /v1/raw/ingest`                |
| **Ledger** | `GET /v1/ledger/transactions`, `GET /v1/ledger/balances` |
| **Wiki**   | `POST /v1/wiki/question`, `GET /v1/wiki/entity/{id}`     |
| **Policy** | `POST /v1/policy`, `POST /v1/policy/evaluate`            |
| **Agent**  | `POST /v1/agents`, `POST /v1/agents/{id}/propose`        |
| **Audit**  | `GET /v1/audit/{id}`, `GET /v1/audit/{id}/proof`         |

[**→ Full API reference**](/api-reference/overview.md)

### Approval Surfaces

Agent proposals can be delivered to Slack, Microsoft Teams, and email through `@brain/surfaces` and the standalone `services/surface-gateway` deployable. These surfaces are not execution rails. They render proposals, capture human decisions, and send every decision through the same Brain approval pipeline: expiry, tenant-scoped identity, policy re-check, terminal-decision idempotency, audit, then execution approval handoff. The gateway has its own DB role and does not receive Ledger or execution outbox privileges.

[**→ Surface approval adapters**](/architecture/surface-approval-adapters.md)

### Networks

| Network            | Role                                                                               |
| ------------------ | ---------------------------------------------------------------------------------- |
| **Base Sepolia**   | Current on-chain execution and proof environment for staging and controlled pilots |
| **Base Mainnet**   | Planned only after external audit, bytecode verification, and operator attestation |
| **External Rails** | Bank APIs, processors, custodians (off-chain)                                      |

### What's Next

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Data Flow</strong></td><td>End-to-end walkthrough of an action.</td><td><a href="/pages/f13dc46dcb9951f17a7148e3db84880b35c5a671">/pages/f13dc46dcb9951f17a7148e3db84880b35c5a671</a></td><td></td></tr><tr><td><strong>Tenant Isolation</strong></td><td>How tenants are separated at every layer.</td><td><a href="/pages/6653bed462d23f79b20417161f16b62ffd97ed9c">/pages/6653bed462d23f79b20417161f16b62ffd97ed9c</a></td><td></td></tr><tr><td><strong>Security and Compliance</strong></td><td>Non-negotiable principles.</td><td><a href="/pages/02a6fa38c72a26d3f8a40cbaad4ac854d7353a1e">/pages/02a6fa38c72a26d3f8a40cbaad4ac854d7353a1e</a></td><td></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.brain.fi/architecture/system-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.