# gzwebsj-163/velthyn architecture

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

- Interactive diagram: https://gitdiagram.com/gzwebsj-163/velthyn
- Repository: https://github.com/gzwebsj-163/velthyn

## Overview

Velthyn is a multi-channel AI agent platform with a macOS Electron client. Its principal workflow accepts a message through an IM, Web, or terminal channel, bridges it into shared chat/session orchestration, uses model and agent capabilities, then returns a response through the channel. The README documents the major agent subsystems and integrations; sampled source confirms the desktop starts a local backend and loads its chat URL. Unsampled implementation details are represented only where documented, and links cite the README when its architecture description is the evidence.

Main entry points: [`server/agent/chat/service.mo`](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/chat/service.mo) (Chat orchestration), [`server/models/bot_factory.mo`](https://github.com/gzwebsj-163/velthyn/blob/main/server/models/bot_factory.mo) (Model routing), [`server/channel`](https://github.com/gzwebsj-163/velthyn/tree/main/server/channel) (IM and Web channels), [`server/channel/web`](https://github.com/gzwebsj-163/velthyn/tree/main/server/channel/web) (Local chat backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Channels and Client"]
  node_channels["IM and Web channels"]
  node_desktop["macOS desktop client<br/>[main.js]"]
end

subgraph group_agent["Agent Runtime"]
  node_chat["Chat orchestration<br/>[service.mo]"]
  node_tools["Agent tools<br/>[tool_manager.mo]"]
  node_memory[("Memory<br/>[service.mo]")]
  node_knowledge["Knowledge RAG<br/>[service.mo]"]
  node_skills["Agent skills<br/>[service.mo]"]
  node_evolution["Self evolution<br/>[executor.mo]"]
  node_prompts["Prompt building<br/>[builder.mo]"]
  node_workspace["Workspace<br/>[service.mo]"]
end

subgraph group_capabilities["Models and Extensions"]
  node_models["Model routing<br/>[bot_factory.mo]"]
  node_mcp["MCP servers<br/>[mcp_client.mo]"]
  node_plugins["Plugins<br/>[plugin_manager.mo]"]
  node_global_skills["Global skill library"]
  node_voice["Voice services<br/>[factory.mo]"]
  node_translation["Translation<br/>[factory.mo]"]
end

subgraph group_platform["Service Platform"]
  node_bridge["Channel bridge"]
  node_local_backend["Local chat backend"]
  node_server_app["Server application<br/>[app.mo]"]
end

node_user(("Chat user"))

node_user -->|"sends message"| node_channels
node_channels -->|"routes input"| node_bridge
node_bridge -->|"dispatches session"| node_chat
node_chat -->|"requests generation"| node_models
node_chat -->|"calls tools"| node_tools
node_chat -->|"uses memory"| node_memory
node_chat -->|"retrieves knowledge"| node_knowledge
node_chat -->|"loads skills"| node_skills
node_chat -->|"invokes evolution"| node_evolution
node_chat -.->|"builds prompts"| node_prompts
node_tools -->|"exposes MCP tools"| node_mcp
node_skills -.->|"loads library"| node_global_skills
node_chat -.->|"uses workspace"| node_workspace
node_server_app -.->|"hosts channels"| node_channels
node_desktop -->|"starts backend"| node_local_backend
node_desktop -->|"loads chat URL"| node_local_backend
node_local_backend -.->|"serves agent chat"| node_chat
node_models -->|"supports voice replies"| node_voice
node_models -.->|"supports translation"| node_translation
node_server_app -.->|"loads plugins"| node_plugins
node_chat -.->|"uses extensions"| node_plugins

click node_channels "https://github.com/gzwebsj-163/velthyn/tree/main/server/channel"
click node_bridge "https://github.com/gzwebsj-163/velthyn/tree/main/server/bridge"
click node_chat "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/chat/service.mo"
click node_models "https://github.com/gzwebsj-163/velthyn/blob/main/server/models/bot_factory.mo"
click node_tools "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/tools/tool_manager.mo"
click node_memory "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/memory/service.mo"
click node_knowledge "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/knowledge/service.mo"
click node_skills "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/skills/service.mo"
click node_evolution "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/evolution/executor.mo"
click node_prompts "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/prompt/builder.mo"
click node_workspace "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/workspace/service.mo"
click node_mcp "https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/tools/mcp/mcp_client.mo"
click node_plugins "https://github.com/gzwebsj-163/velthyn/blob/main/server/plugins/plugin_manager.mo"
click node_global_skills "https://github.com/gzwebsj-163/velthyn/tree/main/server/skills"
click node_voice "https://github.com/gzwebsj-163/velthyn/blob/main/server/voice/factory.mo"
click node_translation "https://github.com/gzwebsj-163/velthyn/blob/main/server/translate/factory.mo"
click node_desktop "https://github.com/gzwebsj-163/velthyn/blob/main/desktop/main.js"
click node_local_backend "https://github.com/gzwebsj-163/velthyn/tree/main/server/channel/web"
click node_server_app "https://github.com/gzwebsj-163/velthyn/blob/main/server/app.mo"

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_channels,node_desktop,node_user toneBlue
class node_chat,node_tools,node_memory,node_knowledge,node_skills,node_evolution,node_prompts,node_workspace toneAmber
class node_models,node_mcp,node_plugins,node_global_skills,node_voice,node_translation toneMint
class node_bridge,node_local_backend,node_server_app toneRose
```

## Components

### Channels and Client

- [IM and Web channels](https://github.com/gzwebsj-163/velthyn/tree/main/server/channel): `server/channel`
- [macOS desktop client](https://github.com/gzwebsj-163/velthyn/blob/main/desktop/main.js): `desktop/main.js`

### Agent Runtime

- [Chat orchestration](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/chat/service.mo): `server/agent/chat/service.mo`
- [Agent tools](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/tools/tool_manager.mo): `server/agent/tools/tool_manager.mo`
- [Memory](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/memory/service.mo): `server/agent/memory/service.mo`
- [Knowledge RAG](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/knowledge/service.mo): `server/agent/knowledge/service.mo`
- [Agent skills](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/skills/service.mo): `server/agent/skills/service.mo`
- [Self evolution](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/evolution/executor.mo): `server/agent/evolution/executor.mo`
- [Prompt building](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/prompt/builder.mo): `server/agent/prompt/builder.mo`
- [Workspace](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/workspace/service.mo): `server/agent/workspace/service.mo`

### Models and Extensions

- [Model routing](https://github.com/gzwebsj-163/velthyn/blob/main/server/models/bot_factory.mo): `server/models/bot_factory.mo`
- [MCP servers](https://github.com/gzwebsj-163/velthyn/blob/main/server/agent/tools/mcp/mcp_client.mo): `server/agent/tools/mcp/mcp_client.mo`
- [Plugins](https://github.com/gzwebsj-163/velthyn/blob/main/server/plugins/plugin_manager.mo): `server/plugins/plugin_manager.mo`
- [Global skill library](https://github.com/gzwebsj-163/velthyn/tree/main/server/skills): `server/skills`
- [Voice services](https://github.com/gzwebsj-163/velthyn/blob/main/server/voice/factory.mo): `server/voice/factory.mo`
- [Translation](https://github.com/gzwebsj-163/velthyn/blob/main/server/translate/factory.mo): `server/translate/factory.mo`

### Service Platform

- [Channel bridge](https://github.com/gzwebsj-163/velthyn/tree/main/server/bridge): `server/bridge`
- [Local chat backend](https://github.com/gzwebsj-163/velthyn/tree/main/server/channel/web): `server/channel/web`
- [Server application](https://github.com/gzwebsj-163/velthyn/blob/main/server/app.mo): `server/app.mo`

### Other components

- **Chat user**

## Connections

- Chat user → IM and Web channels: sends message (evidence: `README.md`)
- IM and Web channels → Channel bridge: routes input (evidence: `README.md`)
- Channel bridge → Chat orchestration: dispatches session (evidence: `README.md`)
- Chat orchestration → Model routing: requests generation (evidence: `README.md`)
- Chat orchestration → Agent tools: calls tools (evidence: `README.md`)
- Chat orchestration → Memory: uses memory (evidence: `README.md`)
- Chat orchestration → Knowledge RAG: retrieves knowledge (evidence: `README.md`)
- Chat orchestration → Agent skills: loads skills (evidence: `README.md`)
- Chat orchestration → Self evolution: invokes evolution (evidence: `README.md`)
- Chat orchestration → Prompt building: builds prompts
- Agent tools → MCP servers: exposes MCP tools (evidence: `README.md`)
- Agent skills → Global skill library: loads library
- Chat orchestration → Workspace: uses workspace
- Server application → IM and Web channels: hosts channels
- macOS desktop client → Local chat backend: starts backend (evidence: `desktop/main.js`)
- macOS desktop client → Local chat backend: loads chat URL (evidence: `desktop/main.js`)
- Local chat backend → Chat orchestration: serves agent chat
- Model routing → Voice services: supports voice replies (evidence: `README.md`)
- Model routing → Translation: supports translation
- Server application → Plugins: loads plugins
- Chat orchestration → Plugins: uses extensions
