> Markdown export: /developers/architecture.md
> HTML: /developers/architecture
---
description: High-level system architecture for operators and integrators — domains and data flow without implementation file paths.
audience: operator
---

# Architecture overview

> **In plain terms:** Eigen Mesh is one app and one database — the browser, MCP clients, and REST APIs all share the same memory, auth, and search logic.

Eigen Mesh is a single SvelteKit application backed by one PostgreSQL instance with pgvector and Apache AGE extensions. Browser UI, REST, and MCP share the same business logic and tenancy model.

## Who this is for

- **Operators** planning or auditing a self-hosted deployment
- **Integrators** who need the system map before wiring MCP or REST clients

## System diagram

```mermaid
flowchart TB
  subgraph clients [Clients]
    Browser[Browser UI]
    MCP[MCP clients]
    REST[Custom REST apps]
  end

  subgraph app [Eigen Mesh app]
    Auth[Better Auth sessions]
    Ingest[Ingestion pipeline]
    Search[Hybrid retrieval]
    QA[Answer composition]
    Sleep[Consolidation]
  end

  subgraph data [PostgreSQL]
    PG[(Relational SoR)]
    Vec[pgvector embeddings]
    AGE[Apache AGE graph]
  end

  Browser --> Auth
  MCP --> Auth
  REST --> Auth
  Auth --> Ingest
  Auth --> Search
  Search --> QA
  Ingest --> PG
  Ingest --> Vec
  Ingest --> AGE
  Search --> Vec
  Search --> PG
  Sleep --> PG
  Sleep --> AGE
```

## Domains

| Domain | Responsibility |
|--------|----------------|
| **Ingestion** | Capture, edit, embed, lexical index, graph sync, activity logging |
| **Client capture queue** | Browser IndexedDB queue, offline sync, NDJSON progress |
| **Retrieval** | Hybrid search (vector + lexical + precomputed graph links), LLM rerank, in-app QA compose |
| **Auth & tenancy** | Better Auth, API keys, RLS via `user_id`, scoped DB role |
| **UI surfaces** | Capture, memory (graph/timeline/notes), chat, activity, settings, API keys |
| **Consolidation** | Nightly salience, ontology prune, communities |

## Deployment topology

| Service | Role |
|---------|------|
| `eigen-app` | SvelteKit Node adapter, port 3000 |
| `eigen-db` | Postgres 16 + pgvector + AGE, port 5432 |

Docker Compose in the [eigen repository](https://github.com/hikaru90/eigen) defines both services. Managed and self-hosted run **identical product code** — only operator and infrastructure differ ([Deployment model](/developers/deployment-model)).

## Integration surfaces

| Surface | Auth | Use case |
|---------|------|----------|
| MCP `/api/mcp` | Bearer API key | AI assistants (Cursor, Claude) — four thought tools |
| REST `/api/*` | Session cookie | Browser UI, custom apps |
| Chat `/api/chat` | Session cookie | Memory assistant with tool loop |

## Security boundaries

- **Tenant isolation:** Row Level Security on all user data; MCP resolves API key → `user_id` before queries
- **Embeddings:** Stored in Postgres for search; **never** returned in MCP, chat, or LLM payloads — [Embeddings boundary](/developers/embeddings-boundary)

## Implementation detail

For file-level architecture maps (canonical paths, key symbols, conflict ledger), see the contributor section:

- [Architecture map L1](/developers/contributor-architecture)
- [Ingestion](/developers/ingestion) · [Retrieval](/developers/retrieval) · [Auth & tenancy](/developers/auth-and-tenancy)

## Troubleshooting

See [Troubleshooting](/developers/troubleshooting) for deployment and integration issues.

## Next steps

- [How memory works](/developers/how-memory-works)
- [MCP overview](/developers/mcp-overview)
- [HTTP API overview](/developers/http-api)