# gavingz/xiaozhi-client architecture

> Architecture diagram of the GitHub repository gavingz/xiaozhi-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gavingz/xiaozhi-client
- Repository: https://github.com/gavingz/xiaozhi-client

## Overview

##### Project type and purpose
- This is an open-source CLI + server tool (“xiaozhi-client”) that:
– Acts as a bridge between a user (via CLI or Web UI) and one or more MCP endpoints (JSON-RPC servers),
– Can itself be exposed as an MCP server over stdio or HTTP/SSE,
– Hosts a React-based Web UI for configuration.
- Key indicators: heavy TypeScript/Node code under `src/`, CLI entrypoints (`cli.ts`), server modules (`WebServer.ts`, `ProxyMCPServer.ts`), plus a `/web` folder for React.

##### Main components
A. CLI Layer
– `cli.ts`, command handlers, services (ProcessManager, DaemonManager, ServiceManager)
– Reads/writes config (`ConfigAdapter`) in workspace directory
– Invokes ServerFactory to start/stop background services
B. Core Server Layer
– UnifiedMCPServer / ProxyMCPServer: manages JSON-RPC connections to remote endpoints
– Transports: `HTTPAdapter`, `WebSocketAdapter`, `StdioAdapter`
– Adapters: `MCPClientAdapter`, `ConfigAdapter`
– Services: `MCPServiceManager`, `MCPService`, health-checks, performance monitor
C. Web UI Server
– `WebServerStandalone` or `WebServer`: serves static React assets, provides configuration REST/SSE/WS endpoints
– React front-end (under `/web/src`), connecting via WebSocket/SSE to server
D. External/Local MCP Endpoints
– Remote Xiaozhi AI MCP endpoints (wss://… )
– Local MCP server processes (e.g. calculator.js) spawned by ProxyMCPServer
E. Docker / Deployment & Config
– Dockerfile, `docker-compose.yml`, `docker-start.sh` for container orchestration
– Mounted config directory (`~/xiaozhi-client`)

##### Relationships and data flows
- User → CLI (stdin/args) → CLI Layer → Core Server Layer
- CLI Layer ↔ ConfigStore (reads/writes `xiaozhi.config.json`)
- Core Server Layer ↔ Remote MCP Servers (over WebSocket or HTTP JSON-RPC)
- Core Server Layer ↔ Local MCP Server processes (spawned child processes, stdio JSON-RPC)
- Core Server Layer ↔ Web UI Server (push config/state via SSE/WebSocket)
- Web UI (browser) ↔ WebServer (HTTP/WS/SSE) for UI actions and real-time status
- Optionally: Core Server Layer exposes itself as MCP Server to other clients via stdio or HTTP/SSE

##### Architectural patterns & design principles
- Modular layering: CLI, Core, Adapters/Transports, Services, UI
- Adapter pattern: abstracting JSON-RPC transport (WS, HTTP, stdio)
- Dependency injection in CLI (`Container.ts`)
- Process isolation: each MCP server runs as separate child process
- Config-driven: behavior controlled entirely via JSON config or UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "CLI Process" 
        direction TB
        CLI["CLI Entrypoint\n(src/cli.ts)"]:::cli
        CLI_BAK["CLI Backup\n(src/cli-backup.ts)"]:::cli
        Container["DI Container\n(src/cli/Container.ts)"]:::cli
        Commands["Commands\n(src/cli/commands/)"]:::cli
        CLI_SVCS["CLI Services\n(src/cli/services/)"]:::cli
        Utils["CLI Utils & Interfaces\n(src/cli/utils/)"]:::cli
    end

    subgraph "Configuration Store"
        direction TB
        ConfigAdapter["ConfigAdapter\n(src/adapters/ConfigAdapter.ts)"]:::config
        ConfigFile["xiaozhi.config.json"]:::config
    end

    subgraph "Daemon Server"
        direction TB
        Factory["ServerFactory\n(src/core/ServerFactory.ts)"]:::core
        Unified["UnifiedMCPServer\n(src/core/UnifiedMCPServer.ts)"]:::core
        Proxy["ProxyMCPServer\n(src/ProxyMCPServer.ts)"]:::core
        
        subgraph "Transports & Adapters"
            direction TB
            WS["WebSocketAdapter\n(src/transports/WebSocketAdapter.ts)"]:::adapter
            HTTP["HTTPAdapter\n(src/transports/HTTPAdapter.ts)"]:::adapter
            STDIO["StdioAdapter\n(src/transports/StdioAdapter.ts)"]:::adapter
            TIF["TransportAdapter Interface\n(src/transports/TransportAdapter.ts)"]:::adapter
            TIDX["Transports Index\n(src/transports/index.ts)"]:::adapter
            MCPClient["MCPClientAdapter\n(src/adapters/MCPClientAdapter.ts)"]:::adapter
        end

        subgraph "Services Layer"
            direction TB
            MCP_SRV["MCPService\n(src/services/MCPService.ts)"]:::core
            MCP_MGR["MCPServiceManager\n(src/services/MCPServiceManager.ts)"]:::core
            MCP_MGR_S["MCPServiceManagerSingleton\n(src/services/MCPServiceManagerSingleton.ts)"]:::core
            Health["HealthChecker\n(src/services/HealthChecker.ts)"]:::core
            Perf["PerformanceMonitor\n(src/services/PerformanceMonitor.ts)"]:::core
            TF["TransportFactory\n(src/services/TransportFactory.ts)"]:::core
            XCM["XiaozhiConnectionManager\n(src/services/XiaozhiConnectionManager.ts)"]:::core
            XCMS["XiaozhiConnectionManagerSingleton\n(src/services/XiaozhiConnectionManagerSingleton.ts)"]:::core
            MCPServer["MCPServer Entry\n(src/services/MCPServer.ts)"]:::core
        end
    end

    subgraph "Web UI Server"
        direction TB
        WebStandalone["WebServerStandalone\n(src/WebServerStandalone.ts)"]:::core
        WebServer["WebServer\n(src/WebServer.ts)"]:::core
    end

    subgraph "React Web UI"
        direction TB
        ReactEntry["main.tsx\n(web/src/main.tsx)"]:::ui
        IndexHTML["index.html\n(web/index.html)"]:::ui
        Components["Components\n(web/src/components/)"]:::ui
        Pages["Pages\n(web/src/pages/)"]:::ui
        Hooks["useWebSocket Hook\n(web/src/hooks/useWebSocket.ts)"]:::ui
        Providers["WebSocketProvider\n(web/src/providers/WebSocketProvider.tsx)"]:::ui
        Stores["State Stores\n(web/src/stores/)"]:::ui
        UIUtils["UI Utils\n(web/src/utils/)"]:::ui
    end

    subgraph "External Systems"
        direction TB
        Remote["Remote MCP Endpoints\n(wss://…)"]:::external
        LocalProc["Local MCP Processes\n(templates/default/mcpServers/calculator.js)"]:::external
        DockerComp["Docker & Compose\n(Dockerfile,\n docker-compose.yml,\n docker-start.sh)"]:::external
        Entrypoint["Docker Entrypoint Script\n(scripts/docker-entrypoint.sh)"]:::external
    end

    %% Connections
    User["User\n(CLI or Browser)"]:::external
    Browser["Browser"]:::external

    %% User flows
    User -->|"stdin/args"| CLI
    CLI -->|"reads/writes"| ConfigAdapter
    ConfigAdapter --> ConfigFile
    CLI -->|"invoke"| Factory
    Factory --> Unified
    Factory --> Proxy

    %% Core internals
    Unified --> WS
    Unified --> HTTP
    Proxy --> STDIO
    WS --> MCPClient
    HTTP --> MCPClient
    STDIO --> MCPClient
    MCPClient --> MCPServer
    MCPServer --> MCP_SRV
    MCP_SRV --> MCP_MGR
    MCP_MGR --> MCP_MGR_S
    MCP_MGR_S --> Health
    MCP_MGR_S --> Perf
    MCP_MGR_S --> TF
    TF --> XCM
    XCM --> XCMS

    %% External endpoints
    Unified -->|"JSON-RPC over WS"| Remote
    HTTP -->|"HTTP JSON-RPC"| Remote
    Proxy -->|"spawn/process"| LocalProc
    STDIO -->|"JSON-RPC over stdio"| LocalProc

    %% Web UI flows
    Unified -->|"push state via SSE/WS"| WebServer
    Proxy -->|"push state via SSE/WS"| WebServer
    Browser -->|"HTTP/SSE/WS"| WebServer
    WebServer -->|static assets| ReactEntry
    ReactEntry --> Components
    ReactEntry --> Pages
    ReactEntry --> Hooks
    Hooks --> Providers
    Providers --> Stores
    Stores --> UIUtils
    ReactEntry --> Browser

    %% Docker
    DockerComp --> Unified
    DockerComp --> WebServer
    Entrypoint --> DockerComp

    %% Click Events
    click CLI "https://github.com/gavingz/xiaozhi-client/blob/main/src/cli.ts"
    click CLI_BAK "https://github.com/gavingz/xiaozhi-client/blob/main/src/cli-backup.ts"
    click Container "https://github.com/gavingz/xiaozhi-client/blob/main/src/cli/Container.ts"
    click Commands "https://github.com/gavingz/xiaozhi-client/tree/main/src/cli/commands/"
    click CLI_SVCS "https://github.com/gavingz/xiaozhi-client/tree/main/src/cli/services/"
    click Utils "https://github.com/gavingz/xiaozhi-client/tree/main/src/cli/utils/"
    click ConfigAdapter "https://github.com/gavingz/xiaozhi-client/blob/main/src/adapters/ConfigAdapter.ts"
    click Factory "https://github.com/gavingz/xiaozhi-client/blob/main/src/core/ServerFactory.ts"
    click Unified "https://github.com/gavingz/xiaozhi-client/blob/main/src/core/UnifiedMCPServer.ts"
    click Proxy "https://github.com/gavingz/xiaozhi-client/blob/main/src/ProxyMCPServer.ts"
    click WS "https://github.com/gavingz/xiaozhi-client/blob/main/src/transports/WebSocketAdapter.ts"
    click HTTP "https://github.com/gavingz/xiaozhi-client/blob/main/src/transports/HTTPAdapter.ts"
    click STDIO "https://github.com/gavingz/xiaozhi-client/blob/main/src/transports/StdioAdapter.ts"
    click TIF "https://github.com/gavingz/xiaozhi-client/blob/main/src/transports/TransportAdapter.ts"
    click TIDX "https://github.com/gavingz/xiaozhi-client/blob/main/src/transports/index.ts"
    click MCPClient "https://github.com/gavingz/xiaozhi-client/blob/main/src/adapters/MCPClientAdapter.ts"
    click MCP_SRV "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/MCPService.ts"
    click MCP_MGR "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/MCPServiceManager.ts"
    click MCP_MGR_S "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/MCPServiceManagerSingleton.ts"
    click Health "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/HealthChecker.ts"
    click Perf "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/PerformanceMonitor.ts"
    click TF "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/TransportFactory.ts"
    click XCM "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/XiaozhiConnectionManager.ts"
    click XCMS "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/XiaozhiConnectionManagerSingleton.ts"
    click MCPServer "https://github.com/gavingz/xiaozhi-client/blob/main/src/services/MCPServer.ts"
    click WebStandalone "https://github.com/gavingz/xiaozhi-client/blob/main/src/WebServerStandalone.ts"
    click WebServer "https://github.com/gavingz/xiaozhi-client/blob/main/src/WebServer.ts"
    click ReactEntry "https://github.com/gavingz/xiaozhi-client/blob/main/web/src/main.tsx"
    click IndexHTML "https://github.com/gavingz/xiaozhi-client/blob/main/web/index.html"
    click Components "https://github.com/gavingz/xiaozhi-client/tree/main/web/src/components/"
    click Pages "https://github.com/gavingz/xiaozhi-client/tree/main/web/src/pages/"
    click Hooks "https://github.com/gavingz/xiaozhi-client/blob/main/web/src/hooks/useWebSocket.ts"
    click Providers "https://github.com/gavingz/xiaozhi-client/blob/main/web/src/providers/WebSocketProvider.tsx"
    click Stores "https://github.com/gavingz/xiaozhi-client/tree/main/web/src/stores/"
    click UIUtils "https://github.com/gavingz/xiaozhi-client/tree/main/web/src/utils/"
    click LocalProc "https://github.com/gavingz/xiaozhi-client/blob/main/templates/default/mcpServers/calculator.js"
    click DockerComp "https://github.com/gavingz/xiaozhi-client/blob/main/docker-compose.yml"
    click Entrypoint "https://github.com/gavingz/xiaozhi-client/blob/main/scripts/docker-entrypoint.sh"

    %% Styles
    classDef cli fill:#add8e6,stroke:#000
    classDef core fill:#90ee90,stroke:#000
    classDef adapter fill:#ffff99,stroke:#000
    classDef ui fill:#ffa500,stroke:#000
    classDef external fill:#d3d3d3,stroke:#000
    classDef config fill:#cccccc,stroke:#000
```
