# edkief/opentalon architecture

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

- Interactive diagram: https://gitdiagram.com/edkief/opentalon
- Repository: https://github.com/edkief/opentalon

## Overview

OpenTalon is a self-hosted personal-agent framework with Telegram, email, embedded-chat, and dashboard entry points. Its main interaction path accepts a chat turn, resolves its thread and agent, invokes the agent runtime with available tools, and persists the conversation. Other major capabilities branch into hybrid RAG memory, multi-agent delegation, scheduled jobs, and visual workflows. The graph uses documented capabilities and sampled call sites; unsampled subsystem wiring is kept intentionally sparse.

Main entry points: [`src/lib/agent`](https://github.com/edkief/opentalon/tree/main/src/lib/agent) (Agent executor), [`src/app/api/chat/route.ts`](https://github.com/edkief/opentalon/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/lib/workflow/engine.ts`](https://github.com/edkief/opentalon/blob/main/src/lib/workflow/engine.ts) (Workflow engine), [`src/app/dashboard`](https://github.com/edkief/opentalon/tree/main/src/app/dashboard) (Web dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_dashboard["Web dashboard"]
  node_chat_api["Chat API<br/>[route.ts]"]
  node_telegram["Telegram channel"]
  node_email["Email channel"]
  node_embed["Embedded chat"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent executor"]
  node_specialist["Specialist agents<br/>[specialist.ts]"]
  node_threads["Thread management"]
  node_conversation_db[("Conversation store<br/>[conversation.ts]")]
end

subgraph group_knowledge["Knowledge and tools"]
  node_tools["Tool registry"]
  node_skills["Skill library<br/>[skills-manager.ts]"]
  node_memory["Hybrid RAG"]
  node_qdrant[("Vector database")]
end

subgraph group_automation["Automation"]
  node_workflow_ui["Workflow editor<br/>[WorkflowCanvas.tsx]"]
  node_workflow_api["Workflow API"]
  node_workflow_engine["Workflow engine<br/>[engine.ts]"]
  node_job_queue["Job queue"]
  node_scheduler["Task scheduler<br/>[index.ts]"]
  node_pg[("PostgreSQL")]
end

subgraph group_control["Control plane"]
  node_config["Agent configuration"]
  node_soul["Agent identity<br/>[soul-manager.ts]"]
  node_logs["Event streaming<br/>[log-bus.ts]"]
end

node_user(("Chat user"))
node_llm["LLM providers"]
node_email_services["IMAP and SMTP"]
node_telegram_service["Telegram service"]

node_user -->|"submits turn"| node_chat_api
node_dashboard -->|"sends chat"| node_chat_api
node_chat_api -->|"ensures thread"| node_threads
node_chat_api -->|"reads and writes"| node_conversation_db
node_chat_api -->|"invokes turn"| node_agent
node_agent -->|"calls tools"| node_tools
node_agent -->|"requests completion"| node_llm
node_agent -->|"emits events"| node_logs
node_telegram -->|"handles messages"| node_agent
node_telegram -->|"polls or sends"| node_telegram_service
node_email -->|"syncs and sends"| node_email_services
node_email -.->|"stores messages"| node_conversation_db
node_embed -->|"processes messages"| node_agent
node_specialist -->|"enqueues jobs"| node_job_queue
node_tools -->|"accesses memories"| node_memory
node_memory -->|"retrieves and stores vectors"| node_qdrant
node_tools -->|"reads skills"| node_skills
node_workflow_ui -->|"manages workflows"| node_workflow_api
node_workflow_api -->|"runs workflow"| node_workflow_engine
node_workflow_engine -->|"stores run state"| node_pg
node_workflow_engine -->|"enqueues ready nodes"| node_job_queue
node_workflow_engine -->|"emits events"| node_logs
node_scheduler -->|"schedules tasks"| node_job_queue
node_job_queue -->|"persists jobs"| node_pg
node_dashboard -->|"manages settings"| node_config
node_dashboard -->|"edits agent identity"| node_soul

click node_dashboard "https://github.com/edkief/opentalon/tree/main/src/app/dashboard"
click node_chat_api "https://github.com/edkief/opentalon/blob/main/src/app/api/chat/route.ts"
click node_telegram "https://github.com/edkief/opentalon/tree/main/src/lib/telegram"
click node_email "https://github.com/edkief/opentalon/tree/main/src/lib/email"
click node_embed "https://github.com/edkief/opentalon/tree/main/src/lib/embed"
click node_agent "https://github.com/edkief/opentalon/tree/main/src/lib/agent"
click node_specialist "https://github.com/edkief/opentalon/blob/main/src/lib/agent/specialist.ts"
click node_threads "https://github.com/edkief/opentalon/tree/main/src/lib/threads"
click node_conversation_db "https://github.com/edkief/opentalon/blob/main/src/lib/db/conversation.ts"
click node_tools "https://github.com/edkief/opentalon/tree/main/src/lib/tools"
click node_skills "https://github.com/edkief/opentalon/blob/main/src/lib/skills/skills-manager.ts"
click node_memory "https://github.com/edkief/opentalon/tree/main/src/lib/memory"
click node_workflow_ui "https://github.com/edkief/opentalon/blob/main/src/components/workflow/WorkflowCanvas.tsx"
click node_workflow_api "https://github.com/edkief/opentalon/tree/main/src/app/api/workflow"
click node_workflow_engine "https://github.com/edkief/opentalon/blob/main/src/lib/workflow/engine.ts"
click node_scheduler "https://github.com/edkief/opentalon/blob/main/src/lib/scheduler/index.ts"
click node_config "https://github.com/edkief/opentalon/tree/main/src/lib/config"
click node_soul "https://github.com/edkief/opentalon/blob/main/src/lib/soul/soul-manager.ts"
click node_logs "https://github.com/edkief/opentalon/blob/main/src/lib/agent/log-bus.ts"

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_chat_api,node_telegram,node_email,node_embed,node_user toneBlue
class node_agent,node_specialist,node_threads,node_conversation_db toneAmber
class node_tools,node_skills,node_memory,node_qdrant toneMint
class node_workflow_ui,node_workflow_api,node_workflow_engine,node_job_queue,node_scheduler,node_pg toneRose
class node_config,node_soul,node_logs,node_llm,node_email_services,node_telegram_service toneIndigo
```

## Components

### User entry points

- [Web dashboard](https://github.com/edkief/opentalon/tree/main/src/app/dashboard): `src/app/dashboard`
- [Chat API](https://github.com/edkief/opentalon/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Telegram channel](https://github.com/edkief/opentalon/tree/main/src/lib/telegram): `src/lib/telegram`
- [Email channel](https://github.com/edkief/opentalon/tree/main/src/lib/email): `src/lib/email`
- [Embedded chat](https://github.com/edkief/opentalon/tree/main/src/lib/embed): `src/lib/embed`

### Agent runtime

- [Agent executor](https://github.com/edkief/opentalon/tree/main/src/lib/agent): `src/lib/agent`
- [Specialist agents](https://github.com/edkief/opentalon/blob/main/src/lib/agent/specialist.ts): `src/lib/agent/specialist.ts`
- [Thread management](https://github.com/edkief/opentalon/tree/main/src/lib/threads): `src/lib/threads`
- [Conversation store](https://github.com/edkief/opentalon/blob/main/src/lib/db/conversation.ts): `src/lib/db/conversation.ts`

### Knowledge and tools

- [Tool registry](https://github.com/edkief/opentalon/tree/main/src/lib/tools): `src/lib/tools`
- [Skill library](https://github.com/edkief/opentalon/blob/main/src/lib/skills/skills-manager.ts): `src/lib/skills/skills-manager.ts`
- [Hybrid RAG](https://github.com/edkief/opentalon/tree/main/src/lib/memory): `src/lib/memory`
- **Vector database**

### Automation

- [Workflow editor](https://github.com/edkief/opentalon/blob/main/src/components/workflow/WorkflowCanvas.tsx): `src/components/workflow/WorkflowCanvas.tsx`
- [Workflow API](https://github.com/edkief/opentalon/tree/main/src/app/api/workflow): `src/app/api/workflow`
- [Workflow engine](https://github.com/edkief/opentalon/blob/main/src/lib/workflow/engine.ts): `src/lib/workflow/engine.ts`
- **Job queue**
- [Task scheduler](https://github.com/edkief/opentalon/blob/main/src/lib/scheduler/index.ts): `src/lib/scheduler/index.ts`
- **PostgreSQL**

### Control plane

- [Agent configuration](https://github.com/edkief/opentalon/tree/main/src/lib/config): `src/lib/config`
- [Agent identity](https://github.com/edkief/opentalon/blob/main/src/lib/soul/soul-manager.ts): `src/lib/soul/soul-manager.ts`
- [Event streaming](https://github.com/edkief/opentalon/blob/main/src/lib/agent/log-bus.ts): `src/lib/agent/log-bus.ts`

### Other components

- **Chat user**
- **LLM providers**
- **IMAP and SMTP**
- **Telegram service**

## Connections

- Chat user → Chat API: submits turn
- Web dashboard → Chat API: sends chat
- Chat API → Thread management: ensures thread
- Chat API → Conversation store: reads and writes
- Chat API → Agent executor: invokes turn
- Agent executor → Tool registry: calls tools
- Agent executor → LLM providers: requests completion
- Agent executor → Event streaming: emits events
- Telegram channel → Agent executor: handles messages
- Telegram channel → Telegram service: polls or sends
- Email channel → IMAP and SMTP: syncs and sends
- Email channel → Conversation store: stores messages
- Embedded chat → Agent executor: processes messages
- Specialist agents → Job queue: enqueues jobs
- Tool registry → Hybrid RAG: accesses memories
- Hybrid RAG → Vector database: retrieves and stores vectors
- Tool registry → Skill library: reads skills
- Workflow editor → Workflow API: manages workflows
- Workflow API → Workflow engine: runs workflow
- Workflow engine → PostgreSQL: stores run state
- Workflow engine → Job queue: enqueues ready nodes
- Workflow engine → Event streaming: emits events
- Task scheduler → Job queue: schedules tasks
- Job queue → PostgreSQL: persists jobs
- Web dashboard → Agent configuration: manages settings
- Web dashboard → Agent identity: edits agent identity