# vellum-ai/vellum-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/vellum-ai/vellum-assistant
- Repository: https://github.com/vellum-ai/vellum-assistant

## Overview

Vellum Assistant is a personal AI assistant that can run locally or on a managed platform, reached through desktop, web, mobile, voice, and messaging channels. A typical interaction arrives through a channel or gateway, is handled by the assistant runtime, and can use memory, tools, and provider-backed inference to produce a reply or take an action. The graph also preserves documented identity, proactive notifications, workflows, and plugin capabilities. Several core modules are named in the source index but not excerpted; their internal links are therefore omitted or marked unverified.

Main entry points: [`assistant/src/runtime/routes/conversation-query-routes.ts`](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/runtime/routes/conversation-query-routes.ts) (Conversation Runtime), [`assistant/src/agent/loop.ts`](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/agent/loop.ts) (Agent Loop), [`assistant/src/providers/inference/connections.ts`](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/inference/connections.ts) (Provider Connections), [`gateway/src/email/inbound-pipeline.ts`](https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/email/inbound-pipeline.ts) (Inbound Email)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Assistant Runtime"]
  node_assistant_runtime["Conversation Runtime"]
  node_agent_loop["Agent Loop<br/>[loop.ts]"]
  node_tools["Computer-Use Tools"]
  node_plugins["Plugin Pipeline<br/>[pipeline.ts]"]
end

subgraph group_intelligence["Memory &amp; Intelligence"]
  node_memory_ingest["Memory Ingestion"]
  node_embeddings["Local Embeddings"]
  node_notifications["Proactive Notifications<br/>[decision-engine.ts]"]
  node_workflows["Workflow Engine<br/>[engine.ts]"]
end

subgraph group_integrations["Channels &amp; Integrations"]
  node_gateway_email["Inbound Email"]
  node_gateway_inbound["Inbound Handler<br/>[handle-inbound.ts]"]
  node_webhook_pipeline["Webhook Pipeline"]
  node_runtime_client["Runtime Client<br/>[client.ts]"]
  node_channels["Messaging Channels<br/>[config.ts]"]
  node_voice["Voice Calls<br/>[call-controller.ts]"]
end

subgraph group_platform["Platform Services"]
  node_config_loader["Config Loader<br/>[loader.ts]"]
  node_llm_schemas["LLM Config<br/>[llm.ts]"]
  node_db[("SQLite Database<br/>[db-connection.ts]")]
  node_connection_resolution["Connection Resolution"]
  node_provider_auth["Provider Auth<br/>[auth.ts]"]
  node_provider_connections["Provider Connections<br/>[connections.ts]"]
  node_model_catalog["Model Catalog<br/>[model-catalog.ts]"]
  node_provider_registry["Provider Registry<br/>[registry.ts]"]
  node_vellum_routing["Vellum Routing"]
  node_route_policy["Route Policy<br/>[route-policy.ts]"]
  node_logger["Logging<br/>[logger.ts]"]
  node_platform_util["Platform Paths<br/>[platform.ts]"]
end

subgraph group_clients["User Clients"]
  node_clients["Desktop, Web &amp; Mobile<br/>[routes.tsx]"]
end

node_user(("User"))

node_user -.->|"uses"| node_clients
node_clients -.->|"sends messages"| node_assistant_runtime
node_channels -.->|"delivers messages"| node_assistant_runtime
node_gateway_email -->|"forwards message"| node_gateway_inbound
node_gateway_email -->|"processes result"| node_webhook_pipeline
node_webhook_pipeline -->|"resets conversation"| node_runtime_client
node_assistant_runtime -->|"loads config"| node_config_loader
node_assistant_runtime -.->|"dispatches turn"| node_agent_loop
node_agent_loop -.->|"invokes tools"| node_tools
node_agent_loop -.->|"uses plugins"| node_plugins
node_assistant_runtime -.->|"checks access"| node_route_policy
node_assistant_runtime -->|"validates settings"| node_llm_schemas
node_assistant_runtime -.->|"exposes ingestion"| node_memory_ingest
node_memory_ingest -.->|"persists memory"| node_db
node_assistant_runtime -.->|"uses local embeddings"| node_embeddings
node_assistant_runtime -.->|"triggers reminders"| node_notifications
node_assistant_runtime -.->|"runs workflows"| node_workflows
node_assistant_runtime -.->|"resolves provider"| node_connection_resolution
node_connection_resolution -.->|"uses connections"| node_provider_connections
node_provider_connections -->|"reads and writes"| node_db
node_provider_auth -->|"derives providers"| node_model_catalog
node_provider_registry -->|"invalidates cache"| node_provider_connections
node_provider_auth -->|"uses routing rules"| node_vellum_routing
node_assistant_runtime -.->|"supports voice"| node_voice
node_config_loader -->|"resolves config path"| node_platform_util
node_logger -->|"uses platform utilities"| node_platform_util

click node_assistant_runtime "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/runtime/routes/conversation-query-routes.ts"
click node_agent_loop "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/agent/loop.ts"
click node_tools "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/api/computer-use-tool.ts"
click node_plugins "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/plugins/pipeline.ts"
click node_config_loader "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/config/loader.ts"
click node_llm_schemas "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/config/schemas/llm.ts"
click node_db "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/persistence/db-connection.ts"
click node_connection_resolution "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/connection-resolution.ts"
click node_provider_auth "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/inference/auth.ts"
click node_provider_connections "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/inference/connections.ts"
click node_model_catalog "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/model-catalog.ts"
click node_provider_registry "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/registry.ts"
click node_vellum_routing "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/vellum-model-routing.ts"
click node_route_policy "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/runtime/auth/route-policy.ts"
click node_logger "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/util/logger.ts"
click node_platform_util "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/util/platform.ts"
click node_memory_ingest "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/plugins/defaults/memory/src/memory-ingest-routes.ts"
click node_embeddings "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/persistence/embeddings/embedding-runtime-manager.ts"
click node_notifications "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/notifications/decision-engine.ts"
click node_workflows "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/workflows/engine.ts"
click node_gateway_email "https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/email/inbound-pipeline.ts"
click node_gateway_inbound "https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/handlers/handle-inbound.ts"
click node_webhook_pipeline "https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/webhook-pipeline.ts"
click node_runtime_client "https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/runtime/client.ts"
click node_channels "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/channels/config.ts"
click node_voice "https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/calls/call-controller.ts"
click node_clients "https://github.com/vellum-ai/vellum-assistant/blob/main/clients/web/src/routes.tsx"

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_assistant_runtime,node_agent_loop,node_tools,node_plugins,node_user toneBlue
class node_memory_ingest,node_embeddings,node_notifications,node_workflows toneAmber
class node_gateway_email,node_gateway_inbound,node_webhook_pipeline,node_runtime_client,node_channels,node_voice toneMint
class node_config_loader,node_llm_schemas,node_db,node_connection_resolution,node_provider_auth,node_provider_connections,node_model_catalog,node_provider_registry,node_vellum_routing,node_route_policy,node_logger,node_platform_util toneRose
class node_clients toneIndigo
```

## Components

### Assistant Runtime

- [Conversation Runtime](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/runtime/routes/conversation-query-routes.ts): `assistant/src/runtime/routes/conversation-query-routes.ts`
- [Agent Loop](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/agent/loop.ts): `assistant/src/agent/loop.ts`
- [Computer-Use Tools](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/api/computer-use-tool.ts): `assistant/src/api/computer-use-tool.ts`
- [Plugin Pipeline](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/plugins/pipeline.ts): `assistant/src/plugins/pipeline.ts`

### Memory & Intelligence

- [Memory Ingestion](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/plugins/defaults/memory/src/memory-ingest-routes.ts): `assistant/src/plugins/defaults/memory/src/memory-ingest-routes.ts`
- [Local Embeddings](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/persistence/embeddings/embedding-runtime-manager.ts): `assistant/src/persistence/embeddings/embedding-runtime-manager.ts`
- [Proactive Notifications](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/notifications/decision-engine.ts): `assistant/src/notifications/decision-engine.ts`
- [Workflow Engine](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/workflows/engine.ts): `assistant/src/workflows/engine.ts`

### Channels & Integrations

- [Inbound Email](https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/email/inbound-pipeline.ts): `gateway/src/email/inbound-pipeline.ts`
- [Inbound Handler](https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/handlers/handle-inbound.ts): `gateway/src/handlers/handle-inbound.ts`
- [Webhook Pipeline](https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/webhook-pipeline.ts): `gateway/src/webhook-pipeline.ts`
- [Runtime Client](https://github.com/vellum-ai/vellum-assistant/blob/main/gateway/src/runtime/client.ts): `gateway/src/runtime/client.ts`
- [Messaging Channels](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/channels/config.ts): `assistant/src/channels/config.ts`
- [Voice Calls](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/calls/call-controller.ts): `assistant/src/calls/call-controller.ts`

### Platform Services

- [Config Loader](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/config/loader.ts): `assistant/src/config/loader.ts`
- [LLM Config](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/config/schemas/llm.ts): `assistant/src/config/schemas/llm.ts`
- [SQLite Database](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/persistence/db-connection.ts): `assistant/src/persistence/db-connection.ts`
- [Connection Resolution](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/connection-resolution.ts): `assistant/src/providers/connection-resolution.ts`
- [Provider Auth](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/inference/auth.ts): `assistant/src/providers/inference/auth.ts`
- [Provider Connections](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/inference/connections.ts): `assistant/src/providers/inference/connections.ts`
- [Model Catalog](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/model-catalog.ts): `assistant/src/providers/model-catalog.ts`
- [Provider Registry](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/registry.ts): `assistant/src/providers/registry.ts`
- [Vellum Routing](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/providers/vellum-model-routing.ts): `assistant/src/providers/vellum-model-routing.ts`
- [Route Policy](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/runtime/auth/route-policy.ts): `assistant/src/runtime/auth/route-policy.ts`
- [Logging](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/util/logger.ts): `assistant/src/util/logger.ts`
- [Platform Paths](https://github.com/vellum-ai/vellum-assistant/blob/main/assistant/src/util/platform.ts): `assistant/src/util/platform.ts`

### User Clients

- [Desktop, Web & Mobile](https://github.com/vellum-ai/vellum-assistant/blob/main/clients/web/src/routes.tsx): `clients/web/src/routes.tsx`

### Other components

- **User**

## Connections

- User → Desktop, Web & Mobile: uses (evidence: `README.md`)
- Desktop, Web & Mobile → Conversation Runtime: sends messages
- Messaging Channels → Conversation Runtime: delivers messages (evidence: `README.md`)
- Inbound Email → Inbound Handler: forwards message (evidence: `gateway/src/email/inbound-pipeline.ts`)
- Inbound Email → Webhook Pipeline: processes result (evidence: `gateway/src/email/inbound-pipeline.ts`)
- Webhook Pipeline → Runtime Client: resets conversation (evidence: `gateway/src/webhook-pipeline.ts`)
- Conversation Runtime → Config Loader: loads config (evidence: `assistant/src/runtime/routes/conversation-query-routes.ts`)
- Conversation Runtime → Agent Loop: dispatches turn
- Agent Loop → Computer-Use Tools: invokes tools (evidence: `README.md`)
- Agent Loop → Plugin Pipeline: uses plugins (evidence: `README.md`)
- Conversation Runtime → Route Policy: checks access (evidence: `README.md`)
- Conversation Runtime → LLM Config: validates settings (evidence: `assistant/src/runtime/routes/conversation-query-routes.ts`)
- Conversation Runtime → Memory Ingestion: exposes ingestion (evidence: `assistant/src/plugins/defaults/memory/src/memory-ingest-routes.ts`)
- Memory Ingestion → SQLite Database: persists memory
- Conversation Runtime → Local Embeddings: uses local embeddings (evidence: `README.md`)
- Conversation Runtime → Proactive Notifications: triggers reminders (evidence: `README.md`)
- Conversation Runtime → Workflow Engine: runs workflows (evidence: `README.md`)
- Conversation Runtime → Connection Resolution: resolves provider (evidence: `assistant/src/runtime/routes/inference-profiles-routes.ts`)
- Connection Resolution → Provider Connections: uses connections (evidence: `assistant/src/providers/connection-resolution.ts`)
- Provider Connections → SQLite Database: reads and writes (evidence: `assistant/src/providers/inference/connections.ts`)
- Provider Auth → Model Catalog: derives providers (evidence: `assistant/src/providers/inference/auth.ts`)
- Provider Registry → Provider Connections: invalidates cache (evidence: `assistant/src/providers/inference/connections.ts`)
- Provider Auth → Vellum Routing: uses routing rules (evidence: `assistant/src/providers/inference/auth.ts`)
- Conversation Runtime → Voice Calls: supports voice (evidence: `README.md`)
- Config Loader → Platform Paths: resolves config path (evidence: `assistant/src/config/loader.ts`)
- Logging → Platform Paths: uses platform utilities (evidence: `assistant/src/util/logger.ts`)
