# tranvanhuy-hichan/nestor-agent architecture

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

- Interactive diagram: https://gitdiagram.com/tranvanhuy-hichan/nestor-agent
- Repository: https://github.com/tranvanhuy-hichan/nestor-agent

## Overview

Nestor is a self-hosted personal AI assistant with a web UI, CLI, API, background gateway, and optional messaging/MCP integrations. The main workflow is a user submitting a chat or task through the UI/API; the backend routes it to an agent run, which can use tools and return a response while persisting sessions. Separate capabilities include document RAG, skills, scheduled work, channels, and office-document generation. Edges are limited to relationships shown in the excerpts, SOURCE INDEX, or README; several unsampled feature links are documented rather than inferred from implementation.

Main entry points: [`app/backend/nestor/services/chat_runner.py`](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/chat_runner.py) (Chat runner), [`app/backend/nestor/main.py`](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/main.py) (HTTP gateway), [`app/backend/nestor/api/chat.py`](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/chat.py) (Chat API), [`app/backend/nestor/services/jobs.py`](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/jobs.py) (Background jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_web["Web application<br/>[App.tsx]"]
  node_chatui["Chat interface<br/>[ChatPage.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_gateway["HTTP gateway<br/>[main.py]"]
  node_chatapi["Chat API<br/>[chat.py]"]
  node_runner["Chat runner<br/>[chat_runner.py]"]
  node_jobsapi["Tasks API<br/>[tasks.py]"]
  node_jobs["Background jobs<br/>[jobs.py]"]
  node_providers["Model providers<br/>[providers.py]"]
end

subgraph group_knowledge["Knowledge and tools"]
  node_knowledge["Knowledge base<br/>[knowledge.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_skills["Skills<br/>[skills.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_office["Office documents<br/>[writer.py]"]
end

subgraph group_automation["Automation and integrations"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
  node_channels["Messaging channels<br/>[channels.py]"]
  node_scheduler["Automations<br/>[scheduler.py]"]
end

subgraph group_state["Local state"]
  node_sessions["Sessions and memory<br/>[sessions.py]"]
  node_database[("SQLite state<br/>[db.py]")]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("User"))
node_external{{"External services"}}

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_chatui
node_chatui -.->|"submits chat"| node_chatapi
node_web -.->|"calls API"| node_gateway
node_gateway -->|"routes requests"| node_chatapi
node_gateway -->|"routes requests"| node_jobsapi
node_chatapi -->|"runs agent"| node_runner
node_chatapi -->|"manages sessions"| node_sessions
node_jobsapi -->|"starts jobs"| node_jobs
node_jobs -->|"uses sessions"| node_sessions
node_sessions -->|"reads and writes"| node_database
node_jobs -->|"reads and writes"| node_database
node_runner -.->|"uses tools"| node_tools
node_runner -.->|"calls models"| node_providers
node_runner -.->|"retrieves documents"| node_knowledge
node_knowledge -.->|"indexes content"| node_embeddings
node_runner -.->|"uses skills"| node_skills
node_tools -.->|"invokes MCP"| node_mcp
node_mcp -.->|"connects servers"| node_external
node_channels -.->|"dispatches tasks"| node_runner
node_channels -.->|"communicates"| node_external
node_scheduler -.->|"schedules work"| node_jobs
node_runner -.->|"creates documents"| node_office
node_gateway -->|"loads settings"| node_config
node_runner -.->|"persists conversation"| node_sessions

click node_web "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/frontend/src/App.tsx"
click node_chatui "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/frontend/src/features/chat/ChatPage.tsx"
click node_gateway "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/main.py"
click node_chatapi "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/chat.py"
click node_runner "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/chat_runner.py"
click node_jobsapi "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/tasks.py"
click node_jobs "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/jobs.py"
click node_sessions "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/sessions.py"
click node_database "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/core/db.py"
click node_config "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/core/config.py"
click node_knowledge "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/knowledge.py"
click node_embeddings "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/embeddings.py"
click node_skills "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/skills.py"
click node_tools "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/tools.py"
click node_mcp "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/mcp_client.py"
click node_channels "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/channels.py"
click node_scheduler "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/scheduler.py"
click node_office "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/vanban/writer.py"
click node_providers "https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/providers.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_web,node_chatui,node_user toneBlue
class node_gateway,node_chatapi,node_runner,node_jobsapi,node_jobs,node_providers toneAmber
class node_knowledge,node_embeddings,node_skills,node_tools,node_office toneMint
class node_mcp,node_channels,node_scheduler toneRose
class node_sessions,node_database,node_config,node_external toneIndigo
```

## Components

### User interfaces

- [Web application](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/frontend/src/App.tsx): `app/frontend/src/App.tsx`
- [Chat interface](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/frontend/src/features/chat/ChatPage.tsx): `app/frontend/src/features/chat/ChatPage.tsx`

### Agent runtime

- [HTTP gateway](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/main.py): `app/backend/nestor/main.py`
- [Chat API](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/chat.py): `app/backend/nestor/api/chat.py`
- [Chat runner](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/chat_runner.py): `app/backend/nestor/services/chat_runner.py`
- [Tasks API](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/tasks.py): `app/backend/nestor/api/tasks.py`
- [Background jobs](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/jobs.py): `app/backend/nestor/services/jobs.py`
- [Model providers](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/providers.py): `app/backend/nestor/services/providers.py`

### Knowledge and tools

- [Knowledge base](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/knowledge.py): `app/backend/nestor/services/knowledge.py`
- [Embeddings](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/embeddings.py): `app/backend/nestor/services/embeddings.py`
- [Skills](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/skills.py): `app/backend/nestor/services/skills.py`
- [Agent tools](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/tools.py): `app/backend/nestor/services/tools.py`
- [Office documents](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/vanban/writer.py): `app/backend/nestor/services/vanban/writer.py`

### Automation and integrations

- [MCP client](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/mcp_client.py): `app/backend/nestor/services/mcp_client.py`
- [Messaging channels](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/api/channels.py): `app/backend/nestor/api/channels.py`
- [Automations](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/scheduler.py): `app/backend/nestor/services/scheduler.py`

### Local state

- [Sessions and memory](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/services/sessions.py): `app/backend/nestor/services/sessions.py`
- [SQLite state](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/core/db.py): `app/backend/nestor/core/db.py`
- [Configuration](https://github.com/tranvanhuy-hichan/nestor-agent/blob/main/app/backend/nestor/core/config.py): `app/backend/nestor/core/config.py`

### Other components

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

## Connections

- User → Web application: uses (evidence: `app/frontend/src/App.tsx`)
- Web application → Chat interface: routes to (evidence: `app/frontend/src/App.tsx`)
- Chat interface → Chat API: submits chat
- Web application → HTTP gateway: calls API
- HTTP gateway → Chat API: routes requests (evidence: `app/backend/nestor/main.py`)
- HTTP gateway → Tasks API: routes requests (evidence: `app/backend/nestor/main.py`)
- Chat API → Chat runner: runs agent (evidence: `app/backend/nestor/api/chat.py`)
- Chat API → Sessions and memory: manages sessions (evidence: `app/backend/nestor/api/chat.py`)
- Tasks API → Background jobs: starts jobs (evidence: `app/backend/nestor/api/tasks.py`)
- Background jobs → Sessions and memory: uses sessions (evidence: `app/backend/nestor/services/jobs.py`)
- Sessions and memory → SQLite state: reads and writes (evidence: `app/backend/nestor/services/sessions.py`)
- Background jobs → SQLite state: reads and writes (evidence: `app/backend/nestor/services/jobs.py`)
- Chat runner → Agent tools: uses tools
- Chat runner → Model providers: calls models
- Chat runner → Knowledge base: retrieves documents
- Knowledge base → Embeddings: indexes content
- Chat runner → Skills: uses skills
- Agent tools → MCP client: invokes MCP (evidence: `app/backend/nestor/services/mcp_client.py`)
- MCP client → External services: connects servers
- Messaging channels → Chat runner: dispatches tasks
- Messaging channels → External services: communicates
- Automations → Background jobs: schedules work
- Chat runner → Office documents: creates documents
- HTTP gateway → Configuration: loads settings (evidence: `app/backend/nestor/main.py`)
- Chat runner → Sessions and memory: persists conversation
