# huabeitech/agent-desk architecture

> Architecture diagram of the GitHub repository huabeitech/agent-desk, 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/huabeitech/agent-desk
- Repository: https://github.com/huabeitech/agent-desk

## Overview

AgentDesk is an AI-first customer-support helpdesk: customer requests become conversations, AI replies use configured agents and knowledge retrieval, and unresolved requests can move to human support and ticket tracking. The product also includes an agent workspace, knowledge-base management, AI workflow editing, and integrations. The graph follows documented product flows and excerpted route/editor wiring; several backend service connections and unsampled subsystem internals are represented only where the README documents them, so those edges cite the README rather than implying source inspection.

Main entry points: [`internal/ai/application/runtime/agent_loop_engine.go`](https://github.com/huabeitech/agent-desk/blob/main/internal/ai/application/runtime/agent_loop_engine.go) (AI Reply Runtime), [`internal/bootstrap/routes.go`](https://github.com/huabeitech/agent-desk/blob/main/internal/bootstrap/routes.go) (Customer API Routes), [`internal/ai/rag`](https://github.com/huabeitech/agent-desk/tree/main/internal/ai/rag) (Knowledge RAG), [`web/app/(dashboard)/dashboard/conversation-monitor/page.tsx`](https://github.com/huabeitech/agent-desk/blob/main/web/app/(dashboard)/dashboard/conversation-monitor/page.tsx) (Conversation Workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Support Entry"]
  node_support_ui["Customer Support UI<br/>[page-client.tsx]"]
  node_api_routes["Customer API Routes<br/>[routes.go]"]
end

subgraph group_conversation["Conversation Operations"]
  node_dashboard["Conversation Workspace<br/>[page.tsx]"]
  node_conversation_detail["Conversation Detail<br/>[detail.tsx]"]
  node_conversation_handlers["Conversation Handlers"]
  node_support_handlers["Support Handlers<br/>[support_handler.go]"]
  node_ticketing["Ticket Workflows<br/>[ticket_handler.go]"]
end

subgraph group_ai["AI and Knowledge"]
  node_ai_runtime["AI Reply Runtime"]
  node_rag["Knowledge RAG"]
  node_knowledge_admin["Knowledge Management"]
  node_retrieval_logs[("Retrieval Logs")]
  node_model_provider["Model Provider"]
  node_vector_store[("Vector Store<br/>[provider.go]")]
end

subgraph group_workflows["Workflow Design"]
  node_workflow_editor["Workflow Editor<br/>[editor.tsx]"]
  node_workflow_data["Initial Workflow Data<br/>[initial-data.ts]"]
  node_workflow_backend["Workflow Runtime<br/>[executor.go]"]
end

subgraph group_platform["Support Platform"]
  node_http_server["HTTP Server<br/>[server.go]"]
  node_support_store[("Support Data Store<br/>[models.go]")]
end

node_customer(("Customer"))
node_agent(("Support Agent"))
node_operator(("Administrator"))

node_customer -->|"starts support"| node_support_ui
node_support_ui -.->|"requests help"| node_api_routes
node_api_routes -->|"routes requests"| node_conversation_handlers
node_api_routes -->|"routes support"| node_support_handlers
node_conversation_handlers -->|"triggers reply"| node_ai_runtime
node_ai_runtime -->|"retrieves evidence"| node_rag
node_rag -.->|"searches vectors"| node_vector_store
node_ai_runtime -.->|"generates answer"| node_model_provider
node_ai_runtime -->|"requests handoff"| node_support_handlers
node_support_handlers -->|"hands off"| node_agent
node_agent -->|"handles conversation"| node_dashboard
node_dashboard -->|"opens detail"| node_conversation_detail
node_dashboard -.->|"loads conversations"| node_conversation_handlers
node_agent -->|"creates tickets"| node_ticketing
node_operator -->|"manages knowledge"| node_knowledge_admin
node_knowledge_admin -.->|"configures retrieval"| node_rag
node_rag -.->|"records retrievals"| node_retrieval_logs
node_operator -->|"designs workflows"| node_workflow_editor
node_workflow_editor -->|"loads defaults"| node_workflow_data
node_workflow_editor -.->|"defines execution"| node_workflow_backend
node_http_server -->|"registers routes"| node_api_routes
node_http_server -.->|"serves product data"| node_support_store

click node_support_ui "https://github.com/huabeitech/agent-desk/blob/main/web/app/(support)/support/page-client.tsx"
click node_api_routes "https://github.com/huabeitech/agent-desk/blob/main/internal/bootstrap/routes.go"
click node_dashboard "https://github.com/huabeitech/agent-desk/blob/main/web/app/(dashboard)/dashboard/conversation-monitor/page.tsx"
click node_conversation_detail "https://github.com/huabeitech/agent-desk/blob/main/web/app/(dashboard)/dashboard/conversation-monitor/_components/detail.tsx"
click node_conversation_handlers "https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/api/conversation_handler.go"
click node_support_handlers "https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/api/support_handler.go"
click node_ai_runtime "https://github.com/huabeitech/agent-desk/blob/main/internal/ai/application/runtime/agent_loop_engine.go"
click node_rag "https://github.com/huabeitech/agent-desk/tree/main/internal/ai/rag"
click node_knowledge_admin "https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/dashboard/knowledge_retrieve_handler.go"
click node_retrieval_logs "https://github.com/huabeitech/agent-desk/blob/main/internal/services/knowledge_retrieve_log_service.go"
click node_ticketing "https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/dashboard/ticket_handler.go"
click node_workflow_editor "https://github.com/huabeitech/agent-desk/blob/main/flowgram-editor/src/editor.tsx"
click node_workflow_data "https://github.com/huabeitech/agent-desk/blob/main/flowgram-editor/src/initial-data.ts"
click node_workflow_backend "https://github.com/huabeitech/agent-desk/blob/main/internal/ai/runtime/workflow/executor.go"
click node_http_server "https://github.com/huabeitech/agent-desk/blob/main/internal/bootstrap/server.go"
click node_support_store "https://github.com/huabeitech/agent-desk/blob/main/internal/models/models.go"
click node_vector_store "https://github.com/huabeitech/agent-desk/blob/main/internal/ai/rag/vectordb/provider.go"

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_support_ui,node_api_routes toneBlue
class node_dashboard,node_conversation_detail,node_conversation_handlers,node_support_handlers,node_ticketing toneAmber
class node_ai_runtime,node_rag,node_knowledge_admin,node_retrieval_logs,node_model_provider,node_vector_store toneMint
class node_workflow_editor,node_workflow_data,node_workflow_backend toneRose
class node_http_server,node_support_store,node_customer,node_agent,node_operator toneIndigo
```

## Components

### Support Entry

- [Customer Support UI](https://github.com/huabeitech/agent-desk/blob/main/web/app/(support)/support/page-client.tsx): `web/app/(support)/support/page-client.tsx`
- [Customer API Routes](https://github.com/huabeitech/agent-desk/blob/main/internal/bootstrap/routes.go): `internal/bootstrap/routes.go`

### Conversation Operations

- [Conversation Workspace](https://github.com/huabeitech/agent-desk/blob/main/web/app/(dashboard)/dashboard/conversation-monitor/page.tsx): `web/app/(dashboard)/dashboard/conversation-monitor/page.tsx`
- [Conversation Detail](https://github.com/huabeitech/agent-desk/blob/main/web/app/(dashboard)/dashboard/conversation-monitor/_components/detail.tsx): `web/app/(dashboard)/dashboard/conversation-monitor/_components/detail.tsx`
- [Conversation Handlers](https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/api/conversation_handler.go): `internal/handlers/api/conversation_handler.go`
- [Support Handlers](https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/api/support_handler.go): `internal/handlers/api/support_handler.go`
- [Ticket Workflows](https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/dashboard/ticket_handler.go): `internal/handlers/dashboard/ticket_handler.go`

### AI and Knowledge

- [AI Reply Runtime](https://github.com/huabeitech/agent-desk/blob/main/internal/ai/application/runtime/agent_loop_engine.go): `internal/ai/application/runtime/agent_loop_engine.go`
- [Knowledge RAG](https://github.com/huabeitech/agent-desk/tree/main/internal/ai/rag): `internal/ai/rag`
- [Knowledge Management](https://github.com/huabeitech/agent-desk/blob/main/internal/handlers/dashboard/knowledge_retrieve_handler.go): `internal/handlers/dashboard/knowledge_retrieve_handler.go`
- [Retrieval Logs](https://github.com/huabeitech/agent-desk/blob/main/internal/services/knowledge_retrieve_log_service.go): `internal/services/knowledge_retrieve_log_service.go`
- **Model Provider**
- [Vector Store](https://github.com/huabeitech/agent-desk/blob/main/internal/ai/rag/vectordb/provider.go): `internal/ai/rag/vectordb/provider.go`

### Workflow Design

- [Workflow Editor](https://github.com/huabeitech/agent-desk/blob/main/flowgram-editor/src/editor.tsx): `flowgram-editor/src/editor.tsx`
- [Initial Workflow Data](https://github.com/huabeitech/agent-desk/blob/main/flowgram-editor/src/initial-data.ts): `flowgram-editor/src/initial-data.ts`
- [Workflow Runtime](https://github.com/huabeitech/agent-desk/blob/main/internal/ai/runtime/workflow/executor.go): `internal/ai/runtime/workflow/executor.go`

### Support Platform

- [HTTP Server](https://github.com/huabeitech/agent-desk/blob/main/internal/bootstrap/server.go): `internal/bootstrap/server.go`
- [Support Data Store](https://github.com/huabeitech/agent-desk/blob/main/internal/models/models.go): `internal/models/models.go`

### Other components

- **Customer**
- **Support Agent**
- **Administrator**

## Connections

- Customer → Customer Support UI: starts support (evidence: `README.md`)
- Customer Support UI → Customer API Routes: requests help
- Customer API Routes → Conversation Handlers: routes requests (evidence: `internal/bootstrap/routes.go`)
- Customer API Routes → Support Handlers: routes support (evidence: `internal/bootstrap/routes.go`)
- Conversation Handlers → AI Reply Runtime: triggers reply (evidence: `README.md`)
- AI Reply Runtime → Knowledge RAG: retrieves evidence (evidence: `internal/ai/application/runtime/agent_loop_engine.go`)
- Knowledge RAG → Vector Store: searches vectors
- AI Reply Runtime → Model Provider: generates answer
- AI Reply Runtime → Support Handlers: requests handoff (evidence: `README.md`)
- Support Handlers → Support Agent: hands off (evidence: `README.md`)
- Support Agent → Conversation Workspace: handles conversation (evidence: `README.md`)
- Conversation Workspace → Conversation Detail: opens detail (evidence: `web/app/(dashboard)/dashboard/conversation-monitor/page.tsx`)
- Conversation Workspace → Conversation Handlers: loads conversations
- Support Agent → Ticket Workflows: creates tickets (evidence: `README.md`)
- Administrator → Knowledge Management: manages knowledge (evidence: `README.md`)
- Knowledge Management → Knowledge RAG: configures retrieval
- Knowledge RAG → Retrieval Logs: records retrievals
- Administrator → Workflow Editor: designs workflows (evidence: `README.md`)
- Workflow Editor → Initial Workflow Data: loads defaults (evidence: `flowgram-editor/src/editor.tsx`)
- Workflow Editor → Workflow Runtime: defines execution
- HTTP Server → Customer API Routes: registers routes (evidence: `internal/bootstrap/server.go`)
- HTTP Server → Support Data Store: serves product data