# pretend-to/mio-chat-backend architecture

> Architecture diagram of the GitHub repository pretend-to/mio-chat-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pretend-to/mio-chat-backend
- Repository: https://github.com/pretend-to/mio-chat-backend

## Overview

##### Main Components
- Backend Server: Represented by the core entry point (app.js) that initializes the server.
- HTTP API Layer: Shows Express handling routes and controllers (found in lib/server/http/controllers and related service and middleware folders).
- WebSocket/Socket.IO Layer: Manage real-time chat interactions (located in lib/server/socket.io, including controllers, middlewares, and services).
- Chat Adapters: Two distinct channels for handling chat protocols:
- OpenAI: Managed in lib/chat/llm which provides adapters (e.g., gemini.js, openai.js).
- Onebot: Managed in lib/chat/onebot with adapters for handling different communication modes (e.g., stdin.js, websocket.js).
- Plugin System: Contains built-in plugins (in lib/plugins) and custom plugins (in plugins/custom). They allow extensibility (e.g., web-plugin functionality for web parsing and external API integrations).
- Configuration Module: Includes configuration files (in the config directory) for server, API keys, and protocol-specific settings provided by the user.
- Presets and Utilities: Additional support directories, such as presets (to define pre-set roles or chat configurations) and utilities (like logger, async queue, imgTools).

##### Relationships and Data Flows
- Incoming client requests are handled by the HTTP layer, which invokes appropriate controllers and services to process file uploads, OpenAI and Onebot messages, and plugin calls.
- Real-time communications are handled separately by the WebSocket/Socket.IO layer, allowing for asynchronous message exchanges.
- The Chat Adapters module converts incoming requests (via HTTP or WebSocket) into protocol-specific actions (either OpenAI or Onebot) and handles responses accordingly.
- The Plugin System intercepts or enhances functionality at key points (e.g., extending API calls, parsing web content) and communicates with both the HTTP and WebSocket layers as required.
- The Configuration Module feeds critical environment settings (such as API keys, server port, and protocol settings) into various components.
- Utility modules support logging, error handling, file operations, and asynchronous operations across all layers.

##### Architectural Patterns and Design Principles
- Layered Architecture: Distinct separation between HTTP routing, WebSocket communications, business logic, and plugin extensions.
- Adapter & Plugin Patterns: Chat adapter modules abstract differences between OpenAI and Onebot protocols; the plugin system provides extensibility to plug in new features dynamically.
- Configuration Management: Centralized management of configuration files ensures decoupling of runtime parameters from code.

##### Relevant Technologies/Frameworks
- Node.js – core runtime environment.
- Express – for HTTP server and route management.
- Socket.IO – handling WebSocket real-time data flow.
- WebSocket (ws) library – for direct WebSocket connections.
- OpenAI API and Gemini API – integration for AI models.
- Various middleware for logging, rate-limiting, and response formatting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Client"]
    class Client client

    %% Backend Server Layer
    App["Backend Server (app.js)"]
    class App backend

    %% Incoming Requests Flow
    Client -->|"request"| App

    %% Subgraph: HTTP API Layer
    subgraph "HTTP API Layer"
        HTTP["HTTP Server (Express)"]
        class HTTP http
        HTTPControllers["Controllers"]
        class HTTPControllers http
        HTTPMiddleware["Middleware"]
        class HTTPMiddleware http
        HTTPServices["Services"]
        class HTTPServices http
        HTTP --> HTTPControllers
        HTTP --> HTTPMiddleware
        HTTP --> HTTPServices
    end
    App --> HTTP

    %% Subgraph: WebSocket/Socket.IO Layer
    subgraph "WebSocket/Socket.IO Layer"
        SocketIO["Socket.IO Server"]
        class SocketIO ws
        WSControllers["Controllers"]
        class WSControllers ws
        WSMiddlewares["Middlewares"]
        class WSMiddlewares ws
        WSServices["Services"]
        class WSServices ws
        SocketIO --> WSControllers
        SocketIO --> WSMiddlewares
        SocketIO --> WSServices
    end
    App --> SocketIO

    %% Subgraph: Chat Adapters
    subgraph "Chat Adapters"
        %% OpenAI Adapters
        OpenAI["OpenAI Adapters"]
        class OpenAI adapter
        GemAdapter["gemini.js"]
        class GemAdapter adapter
        OpenAIFiles["openai.js"]
        class OpenAIFiles adapter
        OpenAI --> GemAdapter
        OpenAI --> OpenAIFiles

        %% Onebot Adapters
        Onebot["Onebot Adapters"]
        class Onebot adapter
        StdinAdapter["stdin.js"]
        class StdinAdapter adapter
        WSAdapter["websocket.js"]
        class WSAdapter adapter
        Onebot --> StdinAdapter
        Onebot --> WSAdapter
    end
    HTTP -->|"calls"| OpenAI
    HTTP -->|"calls"| Onebot
    SocketIO -->|"calls"| OpenAI
    SocketIO -->|"calls"| Onebot

    %% Subgraph: Plugin System
    subgraph "Plugin System"
        %% Built-in Plugins
        BuiltIn["Built-in Plugins"]
        class BuiltIn plugin
        WebPlugin["web-plugin"]
        class WebPlugin plugin
        MCPPlugin["mcp-plugin"]
        class MCPPlugin plugin
        BuiltIn --> WebPlugin
        BuiltIn --> MCPPlugin

        %% Custom Plugins
        Custom["Custom Plugins"]
        class Custom plugin
        ExecPlugin["exec.js"]
        class ExecPlugin plugin
        ParserPlugin["parser.js"]
        class ParserPlugin plugin
        Custom --> ExecPlugin
        Custom --> ParserPlugin
    end
    HTTP ---|"plugin intercept"| BuiltIn
    HTTP ---|"plugin intercept"| Custom
    SocketIO ---|"plugin intercept"| BuiltIn
    SocketIO ---|"plugin intercept"| Custom

    %% Configuration Module
    Config["Configuration Module"]
    class Config config
    ConfigExample["config.example.yaml"]
    class ConfigExample config
    OnebotConfig["onebotConfig.yaml"]
    class OnebotConfig config
    Config --> ConfigExample
    Config --> OnebotConfig
    Config ---|"configures"| App

    %% Presets and Utilities
    subgraph "Presets and Utilities"
        Presets["Presets"]
        class Presets preset
        Utilities["Utilities"]
        class Utilities preset
    end
    Presets ---|"supports"| App
    Utilities ---|"supports"| App

    %% Click Events for Backend Server
    click App "https://github.com/pretend-to/mio-chat-backend/blob/master/app.js"
    
    %% Click Events for HTTP API Layer
    click HTTP "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/http"
    click HTTPControllers "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/http/controllers"
    click HTTPMiddleware "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/http/middleware"
    click HTTPServices "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/http/services"

    %% Click Events for WebSocket/Socket.IO Layer
    click SocketIO "https://github.com/pretend-to/mio-chat-backend/blob/master/lib/server/socket.io"
    click WSControllers "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/socket.io/controllers"
    click WSMiddlewares "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/socket.io/middlewares"
    click WSServices "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/server/socket.io/services"

    %% Click Events for Chat Adapters (OpenAI)
    click OpenAI "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/chat/llm"
    click GemAdapter "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/chat/llm/adapters"
    click OpenAIFiles "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/chat/llm/adapters"

    %% Click Events for Chat Adapters (Onebot)
    click Onebot "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/chat/onebot"
    click StdinAdapter "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/chat/onebot/adapters"
    click WSAdapter "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/chat/onebot/adapters"

    %% Click Events for Plugin System
    click BuiltIn "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/plugins"
    click WebPlugin "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/plugins/web-plugin"
    click MCPPlugin "https://github.com/pretend-to/mio-chat-backend/tree/master/lib/plugins/mcp-plugin"
    click Custom "https://github.com/pretend-to/mio-chat-backend/tree/master/plugins/custom"
    click ExecPlugin "https://github.com/pretend-to/mio-chat-backend/tree/master/plugins/custom"
    click ParserPlugin "https://github.com/pretend-to/mio-chat-backend/tree/master/plugins/custom"

    %% Click Events for Configuration Module
    click Config "https://github.com/pretend-to/mio-chat-backend/tree/master/config"
    click ConfigExample "https://github.com/pretend-to/mio-chat-backend/blob/master/config/config/config.example.yaml"
    click OnebotConfig "https://github.com/pretend-to/mio-chat-backend/blob/master/config/plugins/onebotConfig.yaml"

    %% Click Events for Presets and Utilities
    click Presets "https://github.com/pretend-to/mio-chat-backend/tree/master/presets"
    click Utilities "https://github.com/pretend-to/mio-chat-backend/tree/master/utils"

    %% Styles
    classDef client fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef backend fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef http fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef ws fill:#E6CCFF,stroke:#333,stroke-width:2px;
    classDef adapter fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef plugin fill:#FDEBD0,stroke:#333,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#333,stroke-width:2px;
    classDef preset fill:#D1F2EB,stroke:#333,stroke-width:2px;
```
