# leminhohoho/vde-agent-demo architecture

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

- Interactive diagram: https://gitdiagram.com/leminhohoho/vde-agent-demo
- Repository: https://github.com/leminhohoho/vde-agent-demo

## Overview

vdagent is a multi-agent retail-analytics assistant: a user submits a question in the React chat, the backend schedules an invocation for the orchestrator, and agents collaborate through the backend hub. Agents can use the backend’s authenticated MCP tools to query the warehouse and work with analysis artifacts; the UI follows task and message updates and presents datasets, charts, and reports. The README documents five agent roles and remote gRPC sessions. Some subsystem wiring is represented from documentation because its source was not sampled.

Main entry points: [`backend/vdagent_backend/engine/hub.py`](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/engine/hub.py) (Agent hub), [`backend/vdagent_backend/engine/engine.py`](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/engine/engine.py) (Invocation engine), [`agents/orchestrator/vdagent_orchestrator/agent.py`](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/orchestrator/vdagent_orchestrator/agent.py) (Orchestrator agent), [`frontend/src/api/client.ts`](https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_frontend["React workspace<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_event_stream["Live event stream<br/>[useEventStream.ts]"]
  node_inspector["Results inspector<br/>[Inspector.tsx]"]
end

subgraph group_backend["Backend runtime"]
  node_rest["REST API<br/>[rest.py]"]
  node_sse["SSE API<br/>[sse.py]"]
  node_engine["Invocation engine<br/>[engine.py]"]
  node_hub["Agent hub<br/>[hub.py]"]
  node_event_bus["Event bus<br/>[events.py]"]
  node_repository["Backend repository<br/>[repo.py]"]
  node_backend_db[("Backend SQLite<br/>[database.py]")]
  node_proto["Agent protocol<br/>[agent.proto]"]
end

subgraph group_agents["Agent roles"]
  node_orchestrator["Orchestrator agent<br/>[agent.py]"]
  node_data_agent["Data agent<br/>[agent.py]"]
  node_compare_agent["Compare agent<br/>[agent.py]"]
  node_insight_agent["Insight agent<br/>[agent.py]"]
  node_report_agent["Report agent<br/>[agent.py]"]
  node_mcp_client["Agent MCP client<br/>[mcp_client.py]"]
end

subgraph group_tools["MCP and data"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools<br/>[tools.py]"]
  node_warehouse_sql["Warehouse SQL<br/>[sql.py]"]
  node_artifacts["Artifact storage<br/>[artifacts.py]"]
end

node_user(("Analytics user"))
node_llm{{"LLM service"}}
node_warehouse[("Retail warehouse")]

node_user -->|"asks question"| node_frontend
node_frontend -->|"submits message"| node_api_client
node_api_client -->|"HTTP request"| node_rest
node_rest -->|"starts invocation"| node_engine
node_engine -->|"records run"| node_repository
node_repository -->|"reads and writes"| node_backend_db
node_engine -->|"dispatches turns"| node_hub
node_hub -->|"streams gRPC"| node_orchestrator
node_orchestrator -->|"requests completion"| node_llm
node_orchestrator -->|"requests agent call"| node_hub
node_hub -->|"delivers call"| node_engine
node_engine -->|"dispatches child"| node_hub
node_hub -->|"streams gRPC"| node_data_agent
node_hub -->|"streams gRPC"| node_compare_agent
node_hub -->|"streams gRPC"| node_insight_agent
node_hub -->|"streams gRPC"| node_report_agent
node_data_agent -->|"requests completion"| node_llm
node_compare_agent -->|"requests completion"| node_llm
node_insight_agent -->|"requests completion"| node_llm
node_report_agent -->|"requests completion"| node_llm
node_orchestrator -->|"calls MCP tools"| node_mcp_client
node_mcp_client -->|"HTTP tool requests"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"runs queries"| node_warehouse_sql
node_warehouse_sql -->|"reads warehouse"| node_warehouse
node_mcp_tools -->|"stores artifacts"| node_artifacts
node_engine -->|"publishes events"| node_event_bus
node_event_bus -->|"provides events"| node_sse
node_sse -->|"streams updates"| node_event_stream
node_event_stream -->|"updates workspace"| node_frontend
node_api_client -->|"fetches results"| node_inspector
node_engine -.->|"uses messages"| node_proto

click node_frontend "https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/api/client.ts"
click node_event_stream "https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/events/useEventStream.ts"
click node_inspector "https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/components/inspector/Inspector.tsx"
click node_rest "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/api/rest.py"
click node_sse "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/api/sse.py"
click node_engine "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/engine/engine.py"
click node_hub "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/engine/hub.py"
click node_event_bus "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/events.py"
click node_repository "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/db/repo.py"
click node_backend_db "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/db/database.py"
click node_orchestrator "https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/orchestrator/vdagent_orchestrator/agent.py"
click node_data_agent "https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/data/vdagent_data/agent.py"
click node_compare_agent "https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/compare/vdagent_compare/agent.py"
click node_insight_agent "https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/insight/vdagent_insight/agent.py"
click node_report_agent "https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/report/vdagent_report/agent.py"
click node_mcp_client "https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/orchestrator/vdagent_orchestrator/mcp_client.py"
click node_mcp_server "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/mcp/server.py"
click node_mcp_tools "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/mcp/tools.py"
click node_warehouse_sql "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/mcp/sql.py"
click node_artifacts "https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/db/artifacts.py"
click node_proto "https://github.com/leminhohoho/vde-agent-demo/blob/main/proto/agent.proto"

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_frontend,node_api_client,node_event_stream,node_inspector,node_user toneBlue
class node_rest,node_sse,node_engine,node_hub,node_event_bus,node_repository,node_backend_db,node_proto,node_warehouse toneAmber
class node_orchestrator,node_data_agent,node_compare_agent,node_insight_agent,node_report_agent,node_mcp_client toneMint
class node_mcp_server,node_mcp_tools,node_warehouse_sql,node_artifacts toneRose
class node_llm toneIndigo
```

## Components

### User interface

- [React workspace](https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Live event stream](https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/events/useEventStream.ts): `frontend/src/events/useEventStream.ts`
- [Results inspector](https://github.com/leminhohoho/vde-agent-demo/blob/main/frontend/src/components/inspector/Inspector.tsx): `frontend/src/components/inspector/Inspector.tsx`

### Backend runtime

- [REST API](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/api/rest.py): `backend/vdagent_backend/api/rest.py`
- [SSE API](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/api/sse.py): `backend/vdagent_backend/api/sse.py`
- [Invocation engine](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/engine/engine.py): `backend/vdagent_backend/engine/engine.py`
- [Agent hub](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/engine/hub.py): `backend/vdagent_backend/engine/hub.py`
- [Event bus](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/events.py): `backend/vdagent_backend/events.py`
- [Backend repository](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/db/repo.py): `backend/vdagent_backend/db/repo.py`
- [Backend SQLite](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/db/database.py): `backend/vdagent_backend/db/database.py`
- [Agent protocol](https://github.com/leminhohoho/vde-agent-demo/blob/main/proto/agent.proto): `proto/agent.proto`

### Agent roles

- [Orchestrator agent](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/orchestrator/vdagent_orchestrator/agent.py): `agents/orchestrator/vdagent_orchestrator/agent.py`
- [Data agent](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/data/vdagent_data/agent.py): `agents/data/vdagent_data/agent.py`
- [Compare agent](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/compare/vdagent_compare/agent.py): `agents/compare/vdagent_compare/agent.py`
- [Insight agent](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/insight/vdagent_insight/agent.py): `agents/insight/vdagent_insight/agent.py`
- [Report agent](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/report/vdagent_report/agent.py): `agents/report/vdagent_report/agent.py`
- [Agent MCP client](https://github.com/leminhohoho/vde-agent-demo/blob/main/agents/orchestrator/vdagent_orchestrator/mcp_client.py): `agents/orchestrator/vdagent_orchestrator/mcp_client.py`

### MCP and data

- [MCP server](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/mcp/server.py): `backend/vdagent_backend/mcp/server.py`
- [MCP tools](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/mcp/tools.py): `backend/vdagent_backend/mcp/tools.py`
- [Warehouse SQL](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/mcp/sql.py): `backend/vdagent_backend/mcp/sql.py`
- [Artifact storage](https://github.com/leminhohoho/vde-agent-demo/blob/main/backend/vdagent_backend/db/artifacts.py): `backend/vdagent_backend/db/artifacts.py`

### Other components

- **Analytics user**
- **LLM service**
- **Retail warehouse**

## Connections

- Analytics user → React workspace: asks question
- React workspace → API client: submits message
- API client → REST API: HTTP request
- REST API → Invocation engine: starts invocation
- Invocation engine → Backend repository: records run
- Backend repository → Backend SQLite: reads and writes
- Invocation engine → Agent hub: dispatches turns
- Agent hub → Orchestrator agent: streams gRPC
- Orchestrator agent → LLM service: requests completion
- Orchestrator agent → Agent hub: requests agent call
- Agent hub → Invocation engine: delivers call
- Invocation engine → Agent hub: dispatches child
- Agent hub → Data agent: streams gRPC
- Agent hub → Compare agent: streams gRPC
- Agent hub → Insight agent: streams gRPC
- Agent hub → Report agent: streams gRPC
- Data agent → LLM service: requests completion
- Compare agent → LLM service: requests completion
- Insight agent → LLM service: requests completion
- Report agent → LLM service: requests completion
- Orchestrator agent → Agent MCP client: calls MCP tools
- Agent MCP client → MCP server: HTTP tool requests
- MCP server → MCP tools: dispatches tools
- MCP tools → Warehouse SQL: runs queries
- Warehouse SQL → Retail warehouse: reads warehouse
- MCP tools → Artifact storage: stores artifacts
- Invocation engine → Event bus: publishes events
- Event bus → SSE API: provides events
- SSE API → Live event stream: streams updates
- Live event stream → React workspace: updates workspace
- API client → Results inspector: fetches results
- Invocation engine → Agent protocol: uses messages