# vexa-ai/vexa architecture

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

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

## Overview

Vexa is a meeting-bot and real-time transcription platform with a self-hosted agent lane that turns meeting knowledge into workspace files. The principal workflow is a user request through the gateway, bot capture and transcription, then a live transcript in the Terminal; users can also ask an agent to work with workspace context and commit knowledge. README documents the overall runtime and domain split; sampled source confirms key pipeline and rendering behavior. Several unsampled subsystems are represented at their existing directory paths, so their internal links are limited to documented relationships.

Main entry points: [`core/gateway/services/gateway/src/gateway/app.py`](https://github.com/vexa-ai/vexa/blob/main/core/gateway/services/gateway/src/gateway/app.py) (API gateway), [`core/meetings/services/bot/src/pipeline.ts`](https://github.com/vexa-ai/vexa/blob/main/core/meetings/services/bot/src/pipeline.ts) (Bot service), [`core/meetings/modules/join`](https://github.com/vexa-ai/vexa/tree/main/core/meetings/modules/join) (Meeting platforms), [`core/agent/control_plane`](https://github.com/vexa-ai/vexa/tree/main/core/agent/control_plane) (Agent control plane)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_meeting["Meeting capture"]
  node_bot["Bot service<br/>[pipeline.ts]"]
  node_meeting_platforms["Meeting platforms"]
  node_audio["Audio capture<br/>[audio-pipeline.ts]"]
end

subgraph group_agent["Agent workspace"]
  node_agent_api["Agent control plane"]
  node_runtime["Sandbox runtime"]
  node_agent_worker["Agent turn engine<br/>[engine.py]"]
  node_workspace["Workspace files"]
  node_workspace_store["Workspace store<br/>[client.py]"]
end

subgraph group_platform["Gateway and interfaces"]
  node_gateway["API gateway<br/>[app.py]"]
  node_mcp["MCP service<br/>[app.py]"]
  node_terminal["Terminal workbench"]
end

subgraph group_transcript["Transcription and display"]
  node_gmeet_pipeline["Channel pipeline<br/>[gmeet-pipeline.ts]"]
  node_mixed_pipeline["Mixed pipeline"]
  node_transcription["Transcription service<br/>[main.py]"]
  node_live_transcript["Live transcript view"]
end

node_user(("User"))

node_user -->|"requests bot"| node_gateway
node_gateway -->|"dispatches capture"| node_bot
node_bot -->|"joins meeting"| node_meeting_platforms
node_meeting_platforms -->|"provides audio"| node_audio
node_bot -->|"selects pipeline"| node_gmeet_pipeline
node_bot -->|"selects pipeline"| node_mixed_pipeline
node_gmeet_pipeline -.->|"requests transcription"| node_transcription
node_mixed_pipeline -.->|"requests transcription"| node_transcription
node_bot -->|"streams transcript"| node_gateway
node_user -->|"views transcript"| node_terminal
node_terminal -->|"renders segments"| node_live_transcript
node_live_transcript -.->|"reads live stream"| node_gateway
node_user -->|"asks agent"| node_gateway
node_gateway -->|"routes agent request"| node_agent_api
node_agent_api -->|"dispatches workload"| node_runtime
node_runtime -->|"runs isolated turn"| node_agent_worker
node_agent_worker -->|"reads and writes"| node_workspace
node_workspace_store -.->|"manages files"| node_workspace
node_user -->|"connects tools"| node_mcp
node_mcp -->|"calls API"| node_gateway

click node_gateway "https://github.com/vexa-ai/vexa/blob/main/core/gateway/services/gateway/src/gateway/app.py"
click node_mcp "https://github.com/vexa-ai/vexa/blob/main/core/gateway/services/mcp/src/vexa_mcp/app.py"
click node_terminal "https://github.com/vexa-ai/vexa/tree/main/clients/terminal/src/app"
click node_bot "https://github.com/vexa-ai/vexa/blob/main/core/meetings/services/bot/src/pipeline.ts"
click node_meeting_platforms "https://github.com/vexa-ai/vexa/tree/main/core/meetings/modules/join"
click node_audio "https://github.com/vexa-ai/vexa/blob/main/core/meetings/modules/recording/src/audio-pipeline.ts"
click node_gmeet_pipeline "https://github.com/vexa-ai/vexa/blob/main/core/meetings/modules/gmeet-pipeline/src/gmeet-pipeline.ts"
click node_mixed_pipeline "https://github.com/vexa-ai/vexa/blob/main/core/meetings/modules/mixed-pipeline/src/teams-csrc-gmeet-pipeline.ts"
click node_transcription "https://github.com/vexa-ai/vexa/blob/main/core/meetings/services/transcription/src/transcription/main.py"
click node_live_transcript "https://github.com/vexa-ai/vexa/blob/main/clients/terminal/src/canvas/LiveTranscriptEngine.tsx"
click node_agent_api "https://github.com/vexa-ai/vexa/tree/main/core/agent/control_plane"
click node_runtime "https://github.com/vexa-ai/vexa/tree/main/core/runtime/src/runtime_kernel"
click node_agent_worker "https://github.com/vexa-ai/vexa/blob/main/core/agent/worker/engine.py"
click node_workspace "https://github.com/vexa-ai/vexa/tree/main/core/workspaces/shared"
click node_workspace_store "https://github.com/vexa-ai/vexa/blob/main/core/workspaces/store/client.py"

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_bot,node_meeting_platforms,node_audio,node_user toneBlue
class node_agent_api,node_runtime,node_agent_worker,node_workspace,node_workspace_store toneAmber
class node_gateway,node_mcp,node_terminal toneMint
class node_gmeet_pipeline,node_mixed_pipeline,node_transcription,node_live_transcript toneRose
```

## Components

### Meeting capture

- [Bot service](https://github.com/vexa-ai/vexa/blob/main/core/meetings/services/bot/src/pipeline.ts): `core/meetings/services/bot/src/pipeline.ts`
- [Meeting platforms](https://github.com/vexa-ai/vexa/tree/main/core/meetings/modules/join): `core/meetings/modules/join`
- [Audio capture](https://github.com/vexa-ai/vexa/blob/main/core/meetings/modules/recording/src/audio-pipeline.ts): `core/meetings/modules/recording/src/audio-pipeline.ts`

### Agent workspace

- [Agent control plane](https://github.com/vexa-ai/vexa/tree/main/core/agent/control_plane): `core/agent/control_plane`
- [Sandbox runtime](https://github.com/vexa-ai/vexa/tree/main/core/runtime/src/runtime_kernel): `core/runtime/src/runtime_kernel`
- [Agent turn engine](https://github.com/vexa-ai/vexa/blob/main/core/agent/worker/engine.py): `core/agent/worker/engine.py`
- [Workspace files](https://github.com/vexa-ai/vexa/tree/main/core/workspaces/shared): `core/workspaces/shared`
- [Workspace store](https://github.com/vexa-ai/vexa/blob/main/core/workspaces/store/client.py): `core/workspaces/store/client.py`

### Gateway and interfaces

- [API gateway](https://github.com/vexa-ai/vexa/blob/main/core/gateway/services/gateway/src/gateway/app.py): `core/gateway/services/gateway/src/gateway/app.py`
- [MCP service](https://github.com/vexa-ai/vexa/blob/main/core/gateway/services/mcp/src/vexa_mcp/app.py): `core/gateway/services/mcp/src/vexa_mcp/app.py`
- [Terminal workbench](https://github.com/vexa-ai/vexa/tree/main/clients/terminal/src/app): `clients/terminal/src/app`

### Transcription and display

- [Channel pipeline](https://github.com/vexa-ai/vexa/blob/main/core/meetings/modules/gmeet-pipeline/src/gmeet-pipeline.ts): `core/meetings/modules/gmeet-pipeline/src/gmeet-pipeline.ts`
- [Mixed pipeline](https://github.com/vexa-ai/vexa/blob/main/core/meetings/modules/mixed-pipeline/src/teams-csrc-gmeet-pipeline.ts): `core/meetings/modules/mixed-pipeline/src/teams-csrc-gmeet-pipeline.ts`
- [Transcription service](https://github.com/vexa-ai/vexa/blob/main/core/meetings/services/transcription/src/transcription/main.py): `core/meetings/services/transcription/src/transcription/main.py`
- [Live transcript view](https://github.com/vexa-ai/vexa/blob/main/clients/terminal/src/canvas/LiveTranscriptEngine.tsx): `clients/terminal/src/canvas/LiveTranscriptEngine.tsx`

### Other components

- **User**

## Connections

- User → API gateway: requests bot
- API gateway → Bot service: dispatches capture
- Bot service → Meeting platforms: joins meeting
- Meeting platforms → Audio capture: provides audio
- Bot service → Channel pipeline: selects pipeline (evidence: `core/meetings/services/bot/src/pipeline.ts`)
- Bot service → Mixed pipeline: selects pipeline (evidence: `core/meetings/services/bot/src/pipeline.ts`)
- Channel pipeline → Transcription service: requests transcription
- Mixed pipeline → Transcription service: requests transcription
- Bot service → API gateway: streams transcript
- User → Terminal workbench: views transcript
- Terminal workbench → Live transcript view: renders segments (evidence: `clients/terminal/src/canvas/LiveTranscriptEngine.tsx`)
- Live transcript view → API gateway: reads live stream
- User → API gateway: asks agent
- API gateway → Agent control plane: routes agent request
- Agent control plane → Sandbox runtime: dispatches workload
- Sandbox runtime → Agent turn engine: runs isolated turn
- Agent turn engine → Workspace files: reads and writes (evidence: `core/agent/worker/engine.py`)
- Workspace store → Workspace files: manages files (evidence: `core/workspaces/store/client.py`)
- User → MCP service: connects tools
- MCP service → API gateway: calls API (evidence: `core/gateway/services/mcp/src/vexa_mcp/app.py`)
