# yincongcyincong/telegram-deepseek-bot architecture

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

- Interactive diagram: https://gitdiagram.com/yincongcyincong/telegram-deepseek-bot
- Repository: https://github.com/yincongcyincong/telegram-deepseek-bot

## Overview

##### Project type and purpose
- This is a backend-only, modular Telegram Bot written in Go. Its purpose is to mediate between Telegram users and various AI/LLM backends (DeepSeek, OpenAI, Gemini, etc.), offering features such as streaming chat, image/audio/video processing, RAG (Retrieval-Augmented Generation), function calls, token tracking, and admin commands.

##### File structure
- Top-level entry point:
- main.go – starts the bot, initializes modules, HTTP servers (metrics, pprof), and launches the Telegram long-polling or webhook loop in robot/
- Configuration:
- conf/ – Go structs for all env-var and JSON configs (audio, video, photo, RAG, general) + i18n resources
- param/ – command-line flags
- Core modules:
- robot/ – Telegram update handling, dispatching commands (/chat, /mode, /task, etc.)
- llm/ – Abstraction (llm.go, task.go) plus concrete adapters (deepseek, openai, gemini, huoshan, ollama)
- rag/ – document retrieval & context assembly using data/knowledge
- db/ – persistence layer for users, message history, token usage (supports sqlite3/mysql)
- utils/ – shared helpers (audio conversions, user ID utilities)
- Observability:
- logger/ – structured logging
- metrics/ – Prometheus exporter + pprof
- Static assets & docs:
- static/doc/ – user-facing markdown
- data/knowledge/ – text corpora for RAG
- Deployment & build:
- Dockerfile, Makefile, release.sh, ci.yml
- .github/ISSUE_TEMPLATE, workflows

##### README for additional insights
- Emphasizes easy deployment, environment-driven configuration, Docker support, and the variety of AI backends.
- Lists all bot commands and external dependencies (Telegram API, DeepSeek API, other LLM services, Volcengine for multimodal, DB drivers).

##### Elements
- User → Telegram API → Bot Core → LLM Adapter → External LLM → Bot Core → Telegram API → User
- Bot Core → DB (write/read)
- Bot Core → RAG (read knowledge)
- Bot Core → Metrics endpoint
- Blue for internal modules
- Green for external services
- Orange for data stores
- Gray for static assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User and Telegram
    User["User"]:::external
    TelegramAPI["Telegram API"]:::external

    %% Bot Core Layer
    subgraph "Bot Core" 
        direction TB
        Main["main.go"]:::internal
        Robot["robot/robot.go"]:::internal
    end

    %% Configuration Layer
    subgraph "Configuration Service"
        direction TB
        ConfCore["conf/conf.go"]:::internal
        AudioConf["conf/audio_conf.go"]:::internal
        PhotoConf["conf/photo_conf.go"]:::internal
        VideoConf["conf/video_conf.go"]:::internal
        DeepseekConf["conf/deepseek_conf.go"]:::internal
        RagConf["conf/rag_conf.go"]:::internal
        ToolsConf["conf/tools_conf.go"]:::internal
        I18nEN["conf/i18n/i18n.en.json"]:::static
        I18nZH["conf/i18n/i18n.zh.json"]:::static
    end

    %% Command-Line Parameters
    Param["param/param.go"]:::internal

    %% LLM Adapter Layer
    subgraph "LLM Adapter Layer"
        direction TB
        LLMCore["llm/llm.go"]:::internal
        TaskMgr["llm/task.go"]:::internal
        AdapterDeepseek["llm/deepseek.go"]:::internal
        AdapterOpenAI["llm/openai.go"]:::internal
        AdapterGemini["llm/gemini.go"]:::internal
        AdapterHuoshan["llm/huoshan.go"]:::internal
        AdapterOllama["llm/ollama_deepseek.go"]:::internal
    end

    %% RAG Service
    subgraph "RAG Service"
        direction TB
        RagService["rag/rag.go"]:::internal
        KnowledgeBase["data/knowledge/"]:::datastore
        A2A["data/knowledge/a2a.txt"]:::datastore
        MCP["data/knowledge/mcp.txt"]:::datastore
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DBCore["db/db.go"]:::internal
        UserModel["db/user.go"]:::internal
        MsgRecord["db/msgrecord.go"]:::internal
    end

    %% Observability Layer
    subgraph "Observability Layer"
        direction TB
        Logger["logger/logger.go"]:::internal
        Metrics["metrics/prom.go"]:::internal
        Pprof["metrics/pprof.go"]:::internal
    end

    %% Static Documentation
    StaticDocs["static/doc/*.md"]:::static

    %% External AI Services
    subgraph "External Services"
        direction TB
        DeepSeekAPI["DeepSeek API"]:::external
        OpenAIAPI["OpenAI API"]:::external
        GeminiAPI["Gemini API"]:::external
        HuoshanAPI["Huoshan API"]:::external
        OllamaAPI["Ollama API"]:::external
        Volcengine["Volcengine"]:::external
    end

    %% Flows
    User -->|sends message| TelegramAPI
    TelegramAPI -->|HTTP Update| Robot
    Robot -->|uses| RagService
    RagService -->|reads| KnowledgeBase
    KnowledgeBase --> A2A
    KnowledgeBase --> MCP
    Robot -->|calls| LLMCore
    LLMCore -->|manages tasks| TaskMgr
    TaskMgr --> AdapterDeepseek
    TaskMgr --> AdapterOpenAI
    TaskMgr --> AdapterGemini
    TaskMgr --> AdapterHuoshan
    TaskMgr --> AdapterOllama
    AdapterDeepseek -->|JSON over HTTP| DeepSeekAPI
    AdapterOpenAI -->|JSON over HTTP| OpenAIAPI
    AdapterGemini -->|JSON over HTTP| GeminiAPI
    AdapterHuoshan -->|JSON over HTTP| HuoshanAPI
    AdapterOllama -->|JSON over HTTP| OllamaAPI
    Robot -->|writes/reads| DBCore
    DBCore --> UserModel
    DBCore --> MsgRecord
    Robot -->|logs| Logger
    Robot -->|metrics| Metrics
    Robot -->|profiling| Pprof
    Main -->|loads config| ConfCore
    Main -->|loads flags| Param
    Main -->|serves docs| StaticDocs
    Main -->|starts endpoints| Metrics
    Main -->|starts endpoints| Pprof
    Main -->|initializes robot| Robot

    TelegramAPI -->|sends response| User

    %% Click Events
    click Main "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/main.go"
    click Robot "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/robot/robot.go"
    click ConfCore "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/conf.go"
    click AudioConf "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/audio_conf.go"
    click PhotoConf "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/photo_conf.go"
    click VideoConf "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/video_conf.go"
    click DeepseekConf "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/deepseek_conf.go"
    click RagConf "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/rag_conf.go"
    click ToolsConf "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/tools_conf.go"
    click I18nEN "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/i18n/i18n.en.json"
    click I18nZH "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/conf/i18n/i18n.zh.json"
    click Param "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/param/param.go"
    click LLMCore "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/llm.go"
    click TaskMgr "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/task.go"
    click AdapterDeepseek "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/deepseek.go"
    click AdapterOpenAI "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/openai.go"
    click AdapterGemini "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/gemini.go"
    click AdapterHuoshan "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/huoshan.go"
    click AdapterOllama "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/llm/ollama_deepseek.go"
    click RagService "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/rag/rag.go"
    click A2A "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/data/knowledge/a2a.txt"
    click MCP "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/data/knowledge/mcp.txt"
    click DBCore "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/db/db.go"
    click UserModel "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/db/user.go"
    click MsgRecord "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/db/msgrecord.go"
    click Logger "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/logger/logger.go"
    click Metrics "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/metrics/prom.go"
    click Pprof "https://github.com/yincongcyincong/telegram-deepseek-bot/blob/main/metrics/pprof.go"
    click StaticDocs "https://github.com/yincongcyincong/telegram-deepseek-bot/tree/main/static/doc/"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px
    classDef static fill:#D3D3D3,stroke:#333,stroke-width:1px
```
