# omnigentx/jarvis architecture

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

- Interactive diagram: https://gitdiagram.com/omnigentx/jarvis
- Repository: https://github.com/omnigentx/jarvis

## Overview

Jarvis is a self-hosted, MCP-first AI assistant: a web user chats with a root agent, which can delegate to specialist agents and tools, while sessions and durable memory support later conversations. The Vue dashboard also exposes team activity, approvals, setup, settings, and voice features. The README documents the product-level flows; sampled files support selected internal relationships. Many routes and services are represented at their exact tree paths, but unsampled implementation details and their links are intentionally not inferred.

Main entry points: [`backend/agent.py`](https://github.com/omnigentx/jarvis/blob/main/backend/agent.py) (Agent definitions), [`backend/server.py`](https://github.com/omnigentx/jarvis/blob/main/backend/server.py) (FastAPI server), [`backend/services/memory/candidate_service.py`](https://github.com/omnigentx/jarvis/blob/main/backend/services/memory/candidate_service.py) (Memory candidates), [`frontend/src/App.vue`](https://github.com/omnigentx/jarvis/blob/main/frontend/src/App.vue) (Vue dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web dashboard"]
  node_dashboard["Vue dashboard<br/>[App.vue]"]
  node_api["API client<br/>[api.js]"]
  node_chat_ui["Chat interface<br/>[ChatView.vue]"]
  node_voice_ui["Voice session<br/>[useVoiceSession.js]"]
end

subgraph group_backend["API and runtime"]
  node_server["FastAPI server<br/>[server.py]"]
  node_chat_routes["Chat endpoints<br/>[chat.py]"]
  node_sessions["Session service<br/>[session_service.py]"]
  node_database[("SQLite database<br/>[database.py]")]
  node_activity["Agent activity stream<br/>[activity_stream.py]"]
  node_approvals["Approval service"]
  node_gateways["Messaging gateways<br/>[manager.py]"]
end

subgraph group_agents["Agents and tools"]
  node_agent_runtime["Agent definitions<br/>[agent.py]"]
  node_team_agents["Dynamic teams<br/>[dynamic_agents.py]"]
  node_mcp_tools["MCP tool servers"]
end

subgraph group_memory["Durable memory"]
  node_memory_lifecycle["Memory candidates"]
  node_memory_service["Memory service<br/>[memory_service.py]"]
  node_index_worker["Memory indexing"]
  node_search["Memory retrieval<br/>[orchestrator.py]"]
end

subgraph group_voice["Voice interaction"]
  node_voice_routes["Voice endpoints<br/>[voice.py]"]
  node_voice_runtime["Voice engines"]
end

node_user(("User"))
node_external_services(("External services"))

node_user -->|"uses"| node_dashboard
node_dashboard -.->|"requests"| node_api
node_api -.->|"calls API"| node_server
node_server -->|"loads"| node_agent_runtime
node_agent_runtime -->|"spawns teams"| node_team_agents
node_agent_runtime -->|"uses MCP tools"| node_mcp_tools
node_agent_runtime -->|"maintains sessions"| node_sessions
node_sessions -->|"stores state"| node_database
node_agent_runtime -->|"proposes memories"| node_memory_lifecycle
node_memory_lifecycle -->|"requests approval"| node_approvals
node_memory_lifecycle -->|"persists approved"| node_memory_service
node_memory_service -.->|"queues indexing"| node_index_worker
node_index_worker -.->|"projects for search"| node_search
node_server -->|"initializes"| node_activity
node_user -->|"chats"| node_chat_ui
node_chat_ui -.->|"submits messages"| node_chat_routes
node_chat_routes -.->|"runs agent"| node_agent_runtime
node_user -->|"speaks"| node_voice_ui
node_voice_ui -->|"streams audio"| node_voice_routes
node_voice_routes -.->|"dispatches engines"| node_voice_runtime
node_voice_runtime -.->|"uses optional providers"| node_external_services
node_gateways -->|"dispatches messages"| node_agent_runtime
node_agent_runtime -->|"uses configured LLM"| node_external_services

click node_dashboard "https://github.com/omnigentx/jarvis/blob/main/frontend/src/App.vue"
click node_api "https://github.com/omnigentx/jarvis/blob/main/frontend/src/api.js"
click node_chat_ui "https://github.com/omnigentx/jarvis/blob/main/frontend/src/views/ChatView.vue"
click node_voice_ui "https://github.com/omnigentx/jarvis/blob/main/frontend/src/composables/useVoiceSession.js"
click node_server "https://github.com/omnigentx/jarvis/blob/main/backend/server.py"
click node_chat_routes "https://github.com/omnigentx/jarvis/blob/main/backend/routes/chat.py"
click node_sessions "https://github.com/omnigentx/jarvis/blob/main/backend/services/session_service.py"
click node_database "https://github.com/omnigentx/jarvis/blob/main/backend/core/database.py"
click node_agent_runtime "https://github.com/omnigentx/jarvis/blob/main/backend/agent.py"
click node_team_agents "https://github.com/omnigentx/jarvis/blob/main/backend/services/dynamic_agents.py"
click node_mcp_tools "https://github.com/omnigentx/jarvis/tree/main/backend/tools"
click node_activity "https://github.com/omnigentx/jarvis/blob/main/backend/services/activity_stream.py"
click node_approvals "https://github.com/omnigentx/jarvis/blob/main/backend/services/approval_service.py"
click node_memory_lifecycle "https://github.com/omnigentx/jarvis/blob/main/backend/services/memory/candidate_service.py"
click node_memory_service "https://github.com/omnigentx/jarvis/blob/main/backend/services/memory/memory_service.py"
click node_index_worker "https://github.com/omnigentx/jarvis/blob/main/backend/services/indexing/memory_index_worker.py"
click node_search "https://github.com/omnigentx/jarvis/blob/main/backend/services/retrieval/orchestrator.py"
click node_voice_routes "https://github.com/omnigentx/jarvis/blob/main/backend/routes/voice.py"
click node_voice_runtime "https://github.com/omnigentx/jarvis/blob/main/backend/services/voice_engine_registry.py"
click node_gateways "https://github.com/omnigentx/jarvis/blob/main/backend/services/gateways/manager.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_dashboard,node_api,node_chat_ui,node_voice_ui,node_user toneBlue
class node_server,node_chat_routes,node_sessions,node_database,node_activity,node_approvals,node_gateways toneAmber
class node_agent_runtime,node_team_agents,node_mcp_tools toneMint
class node_memory_lifecycle,node_memory_service,node_index_worker,node_search toneRose
class node_voice_routes,node_voice_runtime,node_external_services toneIndigo
```

## Components

### Web dashboard

- [Vue dashboard](https://github.com/omnigentx/jarvis/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [API client](https://github.com/omnigentx/jarvis/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Chat interface](https://github.com/omnigentx/jarvis/blob/main/frontend/src/views/ChatView.vue): `frontend/src/views/ChatView.vue`
- [Voice session](https://github.com/omnigentx/jarvis/blob/main/frontend/src/composables/useVoiceSession.js): `frontend/src/composables/useVoiceSession.js`

### API and runtime

- [FastAPI server](https://github.com/omnigentx/jarvis/blob/main/backend/server.py): `backend/server.py`
- [Chat endpoints](https://github.com/omnigentx/jarvis/blob/main/backend/routes/chat.py): `backend/routes/chat.py`
- [Session service](https://github.com/omnigentx/jarvis/blob/main/backend/services/session_service.py): `backend/services/session_service.py`
- [SQLite database](https://github.com/omnigentx/jarvis/blob/main/backend/core/database.py): `backend/core/database.py`
- [Agent activity stream](https://github.com/omnigentx/jarvis/blob/main/backend/services/activity_stream.py): `backend/services/activity_stream.py`
- [Approval service](https://github.com/omnigentx/jarvis/blob/main/backend/services/approval_service.py): `backend/services/approval_service.py`
- [Messaging gateways](https://github.com/omnigentx/jarvis/blob/main/backend/services/gateways/manager.py): `backend/services/gateways/manager.py`

### Agents and tools

- [Agent definitions](https://github.com/omnigentx/jarvis/blob/main/backend/agent.py): `backend/agent.py`
- [Dynamic teams](https://github.com/omnigentx/jarvis/blob/main/backend/services/dynamic_agents.py): `backend/services/dynamic_agents.py`
- [MCP tool servers](https://github.com/omnigentx/jarvis/tree/main/backend/tools): `backend/tools`

### Durable memory

- [Memory candidates](https://github.com/omnigentx/jarvis/blob/main/backend/services/memory/candidate_service.py): `backend/services/memory/candidate_service.py`
- [Memory service](https://github.com/omnigentx/jarvis/blob/main/backend/services/memory/memory_service.py): `backend/services/memory/memory_service.py`
- [Memory indexing](https://github.com/omnigentx/jarvis/blob/main/backend/services/indexing/memory_index_worker.py): `backend/services/indexing/memory_index_worker.py`
- [Memory retrieval](https://github.com/omnigentx/jarvis/blob/main/backend/services/retrieval/orchestrator.py): `backend/services/retrieval/orchestrator.py`

### Voice interaction

- [Voice endpoints](https://github.com/omnigentx/jarvis/blob/main/backend/routes/voice.py): `backend/routes/voice.py`
- [Voice engines](https://github.com/omnigentx/jarvis/blob/main/backend/services/voice_engine_registry.py): `backend/services/voice_engine_registry.py`

### Other components

- **User**
- **External services**

## Connections

- User → Vue dashboard: uses (evidence: `README.md`)
- Vue dashboard → API client: requests (evidence: `frontend/src/App.vue`)
- API client → FastAPI server: calls API
- FastAPI server → Agent definitions: loads (evidence: `backend/server.py`)
- Agent definitions → Dynamic teams: spawns teams (evidence: `README.md`)
- Agent definitions → MCP tool servers: uses MCP tools (evidence: `README.md`)
- Agent definitions → Session service: maintains sessions (evidence: `README.md`)
- Session service → SQLite database: stores state (evidence: `backend/services/session_service.py`)
- Agent definitions → Memory candidates: proposes memories (evidence: `backend/services/memory/candidate_service.py`)
- Memory candidates → Approval service: requests approval (evidence: `backend/services/memory/candidate_service.py`)
- Memory candidates → Memory service: persists approved (evidence: `backend/services/memory/candidate_service.py`)
- Memory service → Memory indexing: queues indexing
- Memory indexing → Memory retrieval: projects for search
- FastAPI server → Agent activity stream: initializes (evidence: `backend/server.py`)
- User → Chat interface: chats (evidence: `README.md`)
- Chat interface → Chat endpoints: submits messages
- Chat endpoints → Agent definitions: runs agent
- User → Voice session: speaks (evidence: `README.md`)
- Voice session → Voice endpoints: streams audio (evidence: `frontend/src/composables/useVoiceSession.js`)
- Voice endpoints → Voice engines: dispatches engines
- Voice engines → External services: uses optional providers (evidence: `backend/services/voice_engine_registry.py`)
- Messaging gateways → Agent definitions: dispatches messages (evidence: `backend/services/gateways/manager.py`)
- Agent definitions → External services: uses configured LLM (evidence: `README.md`)