# krishna7604/exa architecture

> Architecture diagram of the GitHub repository krishna7604/exa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishna7604/exa
- Repository: https://github.com/krishna7604/exa

## Overview

exa is a self-hosted, multi-tenant personal AI agent, offered as a web client with a server-hosted loop and a CLI with a machine-hosted loop. Users sign in, start or resume chats, and the agent responds using models and available tools; the web app also exposes memory, scheduled tasks, connectors, and settings. Server APIs apply policy and coordinate sessions, persistence, and approvals. The graph combines sampled call evidence with README-documented architecture; paths for unsampled subsystems point only to existing directories, so some links are intentionally unverified.

Main entry points: [`apps/web/public/app.js`](https://github.com/krishna7604/exa/blob/main/apps/web/public/app.js) (Web application), [`packages/core/src/loop/agent-loop.ts`](https://github.com/krishna7604/exa/blob/main/packages/core/src/loop/agent-loop.ts) (Agent loop), [`apps/server/src/services/session.service.ts`](https://github.com/krishna7604/exa/blob/main/apps/server/src/services/session.service.ts) (Session lifecycle), [`apps/web/public/js/router.js`](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/router.js) (Page router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web application<br/>[app.js]"]
  node_web_router["Page router<br/>[router.js]"]
  node_web_auth["Web authentication<br/>[auth.service.js]"]
  node_web_state["Web client state<br/>[state.js]"]
  node_web_chat["Chat interface<br/>[chat.view.js]"]
  node_web_events["Live chat events<br/>[events.service.js]"]
  node_web_tasks["Scheduled tasks UI<br/>[tasks.view.js]"]
  node_web_pages["Memory and tools pages"]
  node_cli["CLI entry<br/>[main.ts]"]
  node_cli_session["CLI session client<br/>[exa-client.ts]"]
end

subgraph group_server["Server API"]
  node_api["HTTP API<br/>[app.ts]"]
  node_api_routes["API routes<br/>[api.routes.ts]"]
  node_session_controller["Session endpoints"]
  node_session_service["Session lifecycle<br/>[session.service.ts]"]
  node_storage_policy["Storage policy"]
end

subgraph group_agent["Agent runtime"]
  node_server_runtime["Server agent runtime<br/>[server-runtime.ts]"]
  node_core_loop["Agent loop<br/>[agent-loop.ts]"]
  node_permissions["Permission engine"]
  node_tools["Built-in tools"]
  node_connectors["MCP connectors<br/>[mcp.manager.ts]"]
end

subgraph group_models["Model routing"]
  node_router["Model router<br/>[exa.router.ts]"]
  node_gateway["Provider gateway<br/>[gateway.ts]"]
end

subgraph group_data["State and integrations"]
  node_store[("Postgres and local store<br/>[db.ts]")]
  node_session_repository[("Session repository")]
  node_memory_tasks["Memory and task services"]
  node_approval["Approval coordination<br/>[approval-broker.ts]"]
end

node_user(("User"))
node_external_models{{"Model providers"}}
node_external_mcp{{"Remote MCP servers"}}

node_user -->|"uses"| node_web
node_user -->|"runs"| node_cli
node_web -->|"routes pages"| node_web_router
node_web_router -->|"checks sign-in"| node_web_auth
node_web_router -->|"opens chats"| node_web_chat
node_web_auth -->|"loads identity"| node_web_state
node_web_auth -->|"loads account"| node_web_pages
node_web_chat -.->|"subscribes to events"| node_web_events
node_web_events -->|"updates chat state"| node_web_state
node_web -.->|"offers task page"| node_web_tasks
node_web -.->|"offers memory and tools"| node_web_pages
node_cli -->|"starts sessions"| node_cli_session
node_web -->|"calls API"| node_api
node_cli_session -->|"syncs with server"| node_api
node_api -->|"registers routes"| node_api_routes
node_api_routes -->|"routes sessions"| node_session_controller
node_session_controller -->|"delegates"| node_session_service
node_session_service -->|"resolves storage"| node_storage_policy
node_session_controller -.->|"persists sessions"| node_session_repository
node_session_service -.->|"controls server loop"| node_server_runtime
node_session_service -.->|"loads and stores"| node_session_repository
node_session_repository -->|"reads and writes"| node_store
node_server_runtime -->|"runs agent loop"| node_core_loop
node_core_loop -->|"checks actions"| node_permissions
node_core_loop -->|"invokes tools"| node_tools
node_core_loop -->|"requests models"| node_router
node_router -->|"routes completion"| node_gateway
node_gateway -->|"calls providers"| node_external_models
node_tools -.->|"loads MCP tools"| node_connectors
node_connectors -->|"connects remotely"| node_external_mcp
node_core_loop -->|"requests approval"| node_approval
node_approval -.->|"publishes decisions"| node_web_events
node_web_tasks -.->|"manages tasks"| node_memory_tasks
node_web_pages -.->|"manages memory"| node_memory_tasks
node_memory_tasks -.->|"persists records"| node_store

click node_web "https://github.com/krishna7604/exa/blob/main/apps/web/public/app.js"
click node_web_router "https://github.com/krishna7604/exa/blob/main/apps/web/public/js/router.js"
click node_web_auth "https://github.com/krishna7604/exa/blob/main/apps/web/public/js/services/auth.service.js"
click node_web_state "https://github.com/krishna7604/exa/blob/main/apps/web/public/js/state.js"
click node_web_chat "https://github.com/krishna7604/exa/blob/main/apps/web/public/js/views/chat.view.js"
click node_web_events "https://github.com/krishna7604/exa/blob/main/apps/web/public/js/services/events.service.js"
click node_web_tasks "https://github.com/krishna7604/exa/blob/main/apps/web/public/js/views/tasks.view.js"
click node_web_pages "https://github.com/krishna7604/exa/tree/main/apps/web/public/js/views"
click node_cli "https://github.com/krishna7604/exa/blob/main/apps/cli/src/main.ts"
click node_cli_session "https://github.com/krishna7604/exa/blob/main/apps/cli/src/session/exa-client.ts"
click node_api "https://github.com/krishna7604/exa/blob/main/apps/server/src/app.ts"
click node_api_routes "https://github.com/krishna7604/exa/blob/main/apps/server/src/routes/api.routes.ts"
click node_session_controller "https://github.com/krishna7604/exa/blob/main/apps/server/src/controllers/session.controller.ts"
click node_session_service "https://github.com/krishna7604/exa/blob/main/apps/server/src/services/session.service.ts"
click node_storage_policy "https://github.com/krishna7604/exa/blob/main/apps/server/src/services/storage-mode.helper.ts"
click node_server_runtime "https://github.com/krishna7604/exa/blob/main/apps/server/src/runtime/server-runtime.ts"
click node_core_loop "https://github.com/krishna7604/exa/blob/main/packages/core/src/loop/agent-loop.ts"
click node_permissions "https://github.com/krishna7604/exa/blob/main/packages/core/src/permission/permission-engine.ts"
click node_tools "https://github.com/krishna7604/exa/tree/main/packages/tools/src/tools"
click node_connectors "https://github.com/krishna7604/exa/blob/main/packages/tools/src/mcp/mcp.manager.ts"
click node_router "https://github.com/krishna7604/exa/blob/main/packages/router/src/routing/exa.router.ts"
click node_gateway "https://github.com/krishna7604/exa/blob/main/packages/router/src/gateway/gateway.ts"
click node_store "https://github.com/krishna7604/exa/blob/main/packages/store/src/db/db.ts"
click node_session_repository "https://github.com/krishna7604/exa/blob/main/apps/server/src/repositories/session.repository.ts"
click node_memory_tasks "https://github.com/krishna7604/exa/tree/main/apps/server/src/services"
click node_approval "https://github.com/krishna7604/exa/blob/main/apps/server/src/runtime/approval-broker.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_web_router,node_web_auth,node_web_state,node_web_chat,node_web_events,node_web_tasks,node_web_pages,node_cli,node_cli_session,node_user toneBlue
class node_api,node_api_routes,node_session_controller,node_session_service,node_storage_policy toneAmber
class node_server_runtime,node_core_loop,node_permissions,node_tools,node_connectors,node_external_mcp toneMint
class node_router,node_gateway toneRose
class node_store,node_session_repository,node_memory_tasks,node_approval,node_external_models toneIndigo
```

## Components

### User clients

- [Web application](https://github.com/krishna7604/exa/blob/main/apps/web/public/app.js): `apps/web/public/app.js`
- [Page router](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/router.js): `apps/web/public/js/router.js`
- [Web authentication](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/services/auth.service.js): `apps/web/public/js/services/auth.service.js`
- [Web client state](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/state.js): `apps/web/public/js/state.js`
- [Chat interface](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/views/chat.view.js): `apps/web/public/js/views/chat.view.js`
- [Live chat events](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/services/events.service.js): `apps/web/public/js/services/events.service.js`
- [Scheduled tasks UI](https://github.com/krishna7604/exa/blob/main/apps/web/public/js/views/tasks.view.js): `apps/web/public/js/views/tasks.view.js`
- [Memory and tools pages](https://github.com/krishna7604/exa/tree/main/apps/web/public/js/views): `apps/web/public/js/views`
- [CLI entry](https://github.com/krishna7604/exa/blob/main/apps/cli/src/main.ts): `apps/cli/src/main.ts`
- [CLI session client](https://github.com/krishna7604/exa/blob/main/apps/cli/src/session/exa-client.ts): `apps/cli/src/session/exa-client.ts`

### Server API

- [HTTP API](https://github.com/krishna7604/exa/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [API routes](https://github.com/krishna7604/exa/blob/main/apps/server/src/routes/api.routes.ts): `apps/server/src/routes/api.routes.ts`
- [Session endpoints](https://github.com/krishna7604/exa/blob/main/apps/server/src/controllers/session.controller.ts): `apps/server/src/controllers/session.controller.ts`
- [Session lifecycle](https://github.com/krishna7604/exa/blob/main/apps/server/src/services/session.service.ts): `apps/server/src/services/session.service.ts`
- [Storage policy](https://github.com/krishna7604/exa/blob/main/apps/server/src/services/storage-mode.helper.ts): `apps/server/src/services/storage-mode.helper.ts`

### Agent runtime

- [Server agent runtime](https://github.com/krishna7604/exa/blob/main/apps/server/src/runtime/server-runtime.ts): `apps/server/src/runtime/server-runtime.ts`
- [Agent loop](https://github.com/krishna7604/exa/blob/main/packages/core/src/loop/agent-loop.ts): `packages/core/src/loop/agent-loop.ts`
- [Permission engine](https://github.com/krishna7604/exa/blob/main/packages/core/src/permission/permission-engine.ts): `packages/core/src/permission/permission-engine.ts`
- [Built-in tools](https://github.com/krishna7604/exa/tree/main/packages/tools/src/tools): `packages/tools/src/tools`
- [MCP connectors](https://github.com/krishna7604/exa/blob/main/packages/tools/src/mcp/mcp.manager.ts): `packages/tools/src/mcp/mcp.manager.ts`

### Model routing

- [Model router](https://github.com/krishna7604/exa/blob/main/packages/router/src/routing/exa.router.ts): `packages/router/src/routing/exa.router.ts`
- [Provider gateway](https://github.com/krishna7604/exa/blob/main/packages/router/src/gateway/gateway.ts): `packages/router/src/gateway/gateway.ts`

### State and integrations

- [Postgres and local store](https://github.com/krishna7604/exa/blob/main/packages/store/src/db/db.ts): `packages/store/src/db/db.ts`
- [Session repository](https://github.com/krishna7604/exa/blob/main/apps/server/src/repositories/session.repository.ts): `apps/server/src/repositories/session.repository.ts`
- [Memory and task services](https://github.com/krishna7604/exa/tree/main/apps/server/src/services): `apps/server/src/services`
- [Approval coordination](https://github.com/krishna7604/exa/blob/main/apps/server/src/runtime/approval-broker.ts): `apps/server/src/runtime/approval-broker.ts`

### Other components

- **User**
- **Model providers**
- **Remote MCP servers**

## Connections

- User → Web application: uses (evidence: `README.md`)
- User → CLI entry: runs (evidence: `README.md`)
- Web application → Page router: routes pages (evidence: `apps/web/public/app.js`)
- Page router → Web authentication: checks sign-in (evidence: `apps/web/public/js/router.js`)
- Page router → Chat interface: opens chats (evidence: `apps/web/public/js/router.js`)
- Web authentication → Web client state: loads identity (evidence: `apps/web/public/js/services/auth.service.js`)
- Web authentication → Memory and tools pages: loads account (evidence: `apps/web/public/js/services/auth.service.js`)
- Chat interface → Live chat events: subscribes to events (evidence: `apps/web/public/js/views/chat.view.js`)
- Live chat events → Web client state: updates chat state (evidence: `apps/web/public/js/services/events.service.js`)
- Web application → Scheduled tasks UI: offers task page
- Web application → Memory and tools pages: offers memory and tools (evidence: `apps/web/public/app.js`)
- CLI entry → CLI session client: starts sessions (evidence: `apps/cli/src/main.ts`)
- Web application → HTTP API: calls API (evidence: `README.md`)
- CLI session client → HTTP API: syncs with server (evidence: `README.md`)
- HTTP API → API routes: registers routes (evidence: `apps/server/src/app.ts`)
- API routes → Session endpoints: routes sessions (evidence: `apps/server/src/routes/api.routes.ts`)
- Session endpoints → Session lifecycle: delegates (evidence: `apps/server/src/controllers/session.controller.ts`)
- Session lifecycle → Storage policy: resolves storage (evidence: `apps/server/src/services/session.service.ts`)
- Session endpoints → Session repository: persists sessions
- Session lifecycle → Server agent runtime: controls server loop
- Session lifecycle → Session repository: loads and stores
- Session repository → Postgres and local store: reads and writes (evidence: `apps/server/src/repositories/session.repository.ts`)
- Server agent runtime → Agent loop: runs agent loop (evidence: `README.md`)
- Agent loop → Permission engine: checks actions (evidence: `README.md`)
- Agent loop → Built-in tools: invokes tools (evidence: `README.md`)
- Agent loop → Model router: requests models (evidence: `README.md`)
- Model router → Provider gateway: routes completion (evidence: `packages/router/src/routing/exa.router.ts`)
- Provider gateway → Model providers: calls providers (evidence: `README.md`)
- Built-in tools → MCP connectors: loads MCP tools
- MCP connectors → Remote MCP servers: connects remotely (evidence: `README.md`)
- Agent loop → Approval coordination: requests approval (evidence: `README.md`)
- Approval coordination → Live chat events: publishes decisions
- Scheduled tasks UI → Memory and task services: manages tasks
- Memory and tools pages → Memory and task services: manages memory
- Memory and task services → Postgres and local store: persists records