# yincongcyincong/musebot architecture

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

- Interactive diagram: https://gitdiagram.com/yincongcyincong/musebot
- Repository: https://github.com/yincongcyincong/musebot

## Overview

##### Project type and purpose
- This is a full-stack, modular, monolithic Go application (“MuseBot”) that:
- Exposes HTTP/Web APIs
- Hosts a separate Admin UI (React/Vite)
- Connects to many chat platforms (Telegram, Discord, Slack, Lark, DingDing, QQ, WeChat, etc.)
- Integrates with multiple LLM providers (DeepSeek, OpenAI, Gemini, VolcEngine, OpenRouter, 302.AI, etc.)
- Optionally uses RAG (retrieval‐augmented generation) over a knowledge store
- Supports service registration (etcd), metrics, logging, and database (SQLite/MySQL)

##### File structure
- Top-level Go modules:
- main.go: entrypoint, initializes config, logger, router, services
- http/: HTTP server handlers, middleware, service orchestration
- robot/: chat‐platform connectors, one submodule per platform
- llm/: LLM‐provider adapters, one submodule per provider plus mix/mcp logic
- register/: etcd service registration
- db/: data persistence (user, msgrecord, rag_files)
- conf/: application configuration (i18n, LLM, RAG, tools, media)
- admin/: separate Admin UI backend (Go) and front-end files under admin/packages/adminui
- static/: markdown docs for each feature & platform
- metrics/, logger/, utils/, param/ etc.: cross‐cutting concerns
- Deployment files: Dockerfile, Makefile, shell scripts
- Tests under each module

##### README for additional insights
- Primary workflows: user sends message on chat platform → platform connector → core service → LLM adapter → LLM provider → stream response back
- Admin platform manages bots, users, settings (served as SPA)
- Service registry allows multiple MuseBot instances to auto‐register and discover each other
- RAG pulls context from ./data/knowledge via db/rag_files

##### Main components & interactions (to include
a. Clients & entrypoints
- Chat Platforms (Telegram, Discord, Slack, Lark, Ding, QQ, WeChat, custom web)
- Admin UI (browser)
b. API Gateway / HTTP Server
- http/http.go: routes requests from web clients & bots
c. Chat Connectors (“robot/*”)
- One adapter per platform, transforms platform events into internal messages
d. Core Service Layer
- communicate.go: orchestrates session, context tracking
- service.go: high‐level business logic (commands, routing to LLM, tools, RAG)
e. LLM Adapter Layer (“llm/*”)
- Provider‐specific modules (openai.go, deepseek.go, gemini.go, etc.)
- mix.go: dynamic dispatch based on TYPE config
- mcp.go: protocol conversion for function‐calls
f. Persistence
- db/: users, message records, RAG file metadata
- data/knowledge: plaintext or vector store for RAG
g. Configuration & i18n
- conf/: central config loader, env vars, locale files
h. Service Registration & Discovery
- register/etcd.go: auto‐register to etcd
i. Admin Platform
- Go backend (admin/main.go) for API, serves static React build
- React/Vite SPA (admin/packages/adminui) for dashboards, user management
j. Observability
- metrics/prom.go: Prometheus metrics
- logger/logger.go: structured logging

##### Architectural patterns & design principles
- Modular adapter pattern for both chat platforms and LLM providers
- Layered architecture: Transport (HTTP, bots) → Application core → Persistence → External services
- Plugin-style registration of new providers/connectors
- Singleton config + dependency injection via package-level initializers
- Service registry (etcd) for clustering

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Admin UI Tier"
    Browser["Admin UI (React/Vite)"]:::entry
    AdminAPI["Admin Backend (Go)"]:::core
  end

  subgraph "Backend Services Tier"
    subgraph "Clients & Entrypoints"
      Bots["Chat Platforms"]:::entry
      API["HTTP API Server"]:::entry
      AppMain["App Bootstrap (main.go)"]:::core
    end

    subgraph "Core Service"
      CoreSvc["Core Service Layer"]:::core
    end

    subgraph "Adapters"
      LLM["LLM Adapter Layer"]:::core
    end

    subgraph "Persistence"
      DB["Database (SQLite/MySQL)"]:::external
      RAG["RAG Knowledge Store"]:::external
    end

    subgraph "Infrastructure"
      Etcd["etcd Service Registry"]:::external
      Prom["Prometheus Metrics"]:::cross
      Log["Logger"]:::cross
      Conf["Configuration & i18n"]:::cross
    end
  end

  %% Connections
  Browser -->|REST| AdminAPI
  AdminAPI -->|gRPC/HTTP| AppMain

  Bots -->|Webhook| API
  API -->|REST| CoreSvc
  CoreSvc -->|invoke| LLM
  LLM -->|HTTP Streaming| CloudLLM["External LLM Providers"]:::external

  CoreSvc -->|CRUD| DB
  CoreSvc -->|RAG Query| RAG

  CoreSvc -->|register| Etcd
  Etcd -->|heartbeat| CoreSvc

  Prom -->|scrape| AppMain
  CoreSvc -->|log| Log
  AppMain -->|load| Conf
  AdminAPI -->|DB Access| DB

  %% Click Events
  click Browser "https://github.com/yincongcyincong/musebot/tree/main/admin/packages/adminui"
  click AdminAPI "https://github.com/yincongcyincong/musebot/blob/main/admin/main.go"
  click Bots "https://github.com/yincongcyincong/musebot/tree/main/robot/"
  click API "https://github.com/yincongcyincong/musebot/blob/main/http/http.go"
  click AppMain "https://github.com/yincongcyincong/musebot/blob/main/main.go"
  click LLM "https://github.com/yincongcyincong/musebot/blob/main/llm/openai.go"
  click DB "https://github.com/yincongcyincong/musebot/blob/main/db/db.go"
  click RAG "https://github.com/yincongcyincong/musebot/tree/main/data/knowledge"
  click Etcd "https://github.com/yincongcyincong/musebot/blob/main/register/etcd.go"
  click Prom "https://github.com/yincongcyincong/musebot/blob/main/metrics/prom.go"
  click Log "https://github.com/yincongcyincong/musebot/blob/main/logger/logger.go"
  click Conf "https://github.com/yincongcyincong/musebot/blob/main/conf/conf.go"

  %% Styles
  classDef entry fill:#add8e6,stroke:#0000ff
  classDef core fill:#90ee90,stroke:#008000
  classDef external fill:#ffa500,stroke:#cc5500
  classDef cross fill:#d3d3d3,stroke:#808080
```
