# y1jiong/qq-bot-backend architecture

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

- Interactive diagram: https://gitdiagram.com/y1jiong/qq-bot-backend
- Repository: https://github.com/y1jiong/qq-bot-backend

## Overview

##### Project type and purpose
- This is a standalone backend service (“qq-bot-backend”) written in Go.
- Its purpose is to act as a QQ-bot server supporting the OneBot11 protocol (CQ-codes), adapting clients like go-cqhttp and LLOneBot.
- It exposes HTTP and WebSocket endpoints, processes incoming messages/commands, applies business rules, interacts with PostgreSQL, and may call external services (e.g. Mojang).

##### File structure
Top-level directories and files:
- api/… – API-layer definitions for “command” and “message” interfaces (versioned v1).
- internal/controller/… – HTTP/WebSocket controllers that map API requests to service calls.
- internal/service/… – Service façade layer; orchestrates logic and DAO.
- internal/logic/… – Core business logic organized by domain (bot, command, event, file, group, namespace, etc.).
- internal/dao/… – Data access objects handling persistence, with internal subpackages for detailed SQL mappings.
- internal/model/… – Data models (DO = database objects, Entity = domain entities).
- manifest/… – Deployment scripts and PostgreSQL schema.
- utility/… – Shared helper functions (codec, webhook, limiting, etc.).
- main.go – Bootstraps server, loads config, starts HTTP/WebSocket listeners.
- config (hack.example/config.toml, manifest/config.example) – Application configuration.

##### README for additional insights
- Supports OneBot11 CQ-code message reporting formats.
- Adapted for go-cqhttp and LLOneBot.
- Project coding conventions (defer behavior, parameter validation order).

a. Main components
1. External Clients – go-cqhttp / LLOneBot (HTTP + WebSocket).
2. API Layer – Versioned command & message definitions (api/command, api/message).
3. Controller Layer – HTTP handlers and WebSocket connection management (internal/controller).
4. Service Layer – High-level operations orchestration (internal/service).
5. Business Logic Layer – Domain-specific logic (internal/logic/*).
6. DAO Layer – Persistence adapters and repositories (internal/dao/*).
7. Data Store – PostgreSQL (manifest/postgresql).
8. External Third-Party Services – e.g. Mojang API (internal/logic/thirdparty).
9. Cross-cutting Utilities – Configuration, logging, metrics (otel), codec utilities.
10. Deployment & Configuration – Kubernetes/Shell Scripts, TOML configs in manifest.

b. Relationships and interactions
- Clients send requests (HTTP/WebSocket) → API Layer.
- API definitions route to Controller methods.
- Controllers call Service functions.
- Services invoke Business Logic and coordinate transactions.
- Logic layer may call other sub-modules (bot, event, file, etc.) and then call DAOs.
- DAO layer executes SQL against PostgreSQL and returns domain models.
- Logic returns results to Service → Controller → serializes response back via HTTP/WebSocket.
- Some logic modules call external HTTP APIs (e.g. Mojang).
- Configuration and telemetry (OpenTelemetry) loaded at startup via cfg logic.

c. Architectural patterns and principles
- Layered (onion) architecture: API → Controller → Service → Logic → DAO → DB.
- Clear separation of concerns: controllers are thin, all heavy lifting in logic.
- Versioned API definitions allow backward compatibility (api/command/v1).
- Internal packages prevent accidental external imports.
- Use of model DO vs entity for strict DB mapping vs domain representation.
- Utility packages for cross-cutting concerns (codec, rate limiting, runes).

d. Key technologies / frameworks
- Go (modules: go.mod).
- HTTP + Gorilla WebSocket (in controller/websocket.go) or standard library.
- PostgreSQL (manifest scripts, internal/dao uses database/sql or an ORM).
- TOML for configuration (hack.example/config.toml).
- OpenTelemetry for tracing (internal/logic/cfg/otel.go).

##### Diagramming recommendations
– External systems (clients, third-party APIs)
– Public interface components (API layer, controllers)
– Internal processing (service & logic layers)
– Data persistence (DAO & DB)
– Cross-cutting utilities (config, telemetry).
– Clients → API → Controller → Service → Logic → DAO → DB
– DAO → DB (query/response) → Logic → … → Clients
– Logic → External API (e.g. Mojang)
– Bootstrapping → Config Loader → Controllers & Telemetry
- Versioning on the API layer.
- Notes on deployment: config files, manifest scripts, database initialization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        direction TB
        ClientsHTTP["go-cqhttp / LLOneBot (HTTP)"]:::external
        ClientsWS["go-cqhttp / LLOneBot (WebSocket)"]:::external
    end

    %% API Layer
    subgraph "Public API Layer"
        direction TB
        CommandAPI["Command Definitions (api/command/v1)"]:::api
        MessageAPI["Message Definitions (api/message/v1)"]:::api
    end

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        CmdCtrlHTTP["Command HTTP Handler (internal/controller/command/command.go)"]:::controller
        CmdCtrlV1["Command HTTP Handler v1 (internal/controller/command/command_v1_command.go)"]:::controller
        MsgCtrlHTTP["Message HTTP Handler (internal/controller/message/message.go)"]:::controller
        MsgCtrlV1["Message HTTP Handler v1 (internal/controller/message/message_v1_message.go)"]:::controller
        WSManager["WebSocket Manager (internal/controller/websocket.go)"]:::controller
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ServiceFacades["Orchestration Facade (internal/service)"]:::service
        ServiceConfig["Service Config Loader (internal/service/cfg.go)"]:::config
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        CoreLogic["Core Logic (internal/logic)"]:::logic
        ThirdPartyLogic["Third-Party Logic (internal/logic/thirdparty/thirdparty.go)"]:::logic
        MojangClient["Mojang API Client (internal/logic/thirdparty/mojang.go)"]:::logic
        LogicConfig["Logic Config (internal/logic/cfg)"]:::config
    end

    %% DAO Layer
    subgraph "DAO Layer"
        direction TB
        Persistence["Persistence Adapters (internal/dao)"]:::dao
    end

    %% Data Models
    subgraph "Data Models"
        direction TB
        ModelDO["Database Objects (internal/model/do)"]:::model
        ModelEntity["Domain Entities (internal/model/entity)"]:::model
    end

    %% Database
    PostgreSQL["PostgreSQL Database"]:::external

    %% Utilities
    subgraph "Cross-cutting Utilities"
        direction TB
        Utilities["Helpers (utility)"]:::utility
    end

    %% Configuration & Observability
    MainApp["Application Entry Point (main.go)"]:::service
    Telemetry["OpenTelemetry"]:::config

    %% Deployment & Manifest
    subgraph "Deployment & Configuration"
        direction TB
        DeployScripts["Deployment Scripts (manifest/deploy/auto.sh)"]:::deployment
        DBSchema["DB Schema (manifest/postgresql/sql/qq_bot.sql)"]:::deployment
        ConfigFiles["Config Examples (manifest/config.example/config.toml, hack.example/config.toml)"]:::deployment
    end

    %% Flows
    ClientsHTTP -->|HTTP Request| CommandAPI
    ClientsHTTP -->|HTTP Request| MessageAPI
    ClientsWS -->|WebSocket Req| WSManager

    CommandAPI -->|routes to| CmdCtrlHTTP
    CommandAPI -->|routes to| CmdCtrlV1
    MessageAPI -->|routes to| MsgCtrlHTTP
    MessageAPI -->|routes to| MsgCtrlV1
    WSManager -->|dispatches to| ServiceFacades

    CmdCtrlHTTP -->|calls| ServiceFacades
    CmdCtrlV1 -->|calls| ServiceFacades
    MsgCtrlHTTP -->|calls| ServiceFacades
    MsgCtrlV1 -->|calls| ServiceFacades

    ServiceFacades -->|orchestrates| CoreLogic
    ServiceFacades -->|uses config| ServiceConfig

    CoreLogic -->|executes domain logic| Persistence
    CoreLogic -->|calls| ThirdPartyLogic
    ThirdPartyLogic -->|invokes| MojangClient
    CoreLogic -->|reads config| LogicConfig

    Persistence -->|queries| PostgreSQL
    Persistence -->|returns DO| ModelDO
    ModelDO -->|mapped to| ModelEntity

    MainApp -->|bootstraps| ServiceConfig
    MainApp -->|bootstraps| LogicConfig
    MainApp -->|initializes| Telemetry
    MainApp -->|starts| CmdCtrlHTTP
    MainApp -->|starts| WSManager

    Utilities -->|used by| CoreLogic
    Utilities -->|used by| ServiceFacades
    Utilities -->|used by| Persistence

    DeployScripts -->|provision| PostgreSQL
    ConfigFiles -->|provide| MainApp
    DBSchema -->|init DB| PostgreSQL

    %% Click Events
    click CommandAPI "https://github.com/y1jiong/qq-bot-backend/blob/main/api/command/v1/command.go"
    click MessageAPI "https://github.com/y1jiong/qq-bot-backend/blob/main/api/message/v1/message.go"
    click CmdCtrlHTTP "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/controller/command/command.go"
    click CmdCtrlV1 "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/controller/command/command_v1_command.go"
    click MsgCtrlHTTP "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/controller/message/message.go"
    click MsgCtrlV1 "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/controller/message/message_v1_message.go"
    click WSManager "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/controller/websocket.go"
    click ServiceFacades "https://github.com/y1jiong/qq-bot-backend/tree/main/internal/service"
    click CoreLogic "https://github.com/y1jiong/qq-bot-backend/tree/main/internal/logic"
    click ThirdPartyLogic "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/logic/thirdparty/thirdparty.go"
    click MojangClient "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/logic/thirdparty/mojang.go"
    click Persistence "https://github.com/y1jiong/qq-bot-backend/tree/main/internal/dao"
    click ModelDO "https://github.com/y1jiong/qq-bot-backend/tree/main/internal/model/do"
    click ModelEntity "https://github.com/y1jiong/qq-bot-backend/tree/main/internal/model/entity"
    click LogicConfig "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/logic/cfg/cfg.go"
    click ServiceConfig "https://github.com/y1jiong/qq-bot-backend/blob/main/internal/service/cfg.go"
    click Utilities "https://github.com/y1jiong/qq-bot-backend/tree/main/utility"
    click DeployScripts "https://github.com/y1jiong/qq-bot-backend/blob/main/manifest/deploy/auto.sh"
    click DBSchema "https://github.com/y1jiong/qq-bot-backend/blob/main/manifest/postgresql/sql/qq_bot.sql"
    click ConfigFiles "https://github.com/y1jiong/qq-bot-backend/blob/main/manifest/config.example/config.toml"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#ccf,stroke:#333,stroke-width:1px
    classDef controller fill:#ffcccc,stroke:#333,stroke-width:1px
    classDef service fill:#cfc,stroke:#333,stroke-width:1px
    classDef logic fill:#cff,stroke:#333,stroke-width:1px
    classDef dao fill:#fcf,stroke:#333,stroke-width:1px
    classDef model fill:#ffc,stroke:#333,stroke-width:1px
    classDef utility fill:#efe,stroke:#333,stroke-width:1px
    classDef config fill:#ecc,stroke:#333,stroke-width:1px
    classDef deployment fill:#eef,stroke:#333,stroke-width:1px
```
