System Architecture

This document describes the overall architecture of the onebots system, including server and client components.

Overall Architecture

Component Description

Server Components

1. Application Layer

• BaseApp: Core application class, manages HTTP/WebSocket servers, routing, middleware
• Config Management: YAML configuration file parsing and management
• Route Management: Koa router for handling HTTP requests

2. Adapter Layer

• Platform Adapters: Connect to different IM platforms (QQ, WeChat, Kook, etc.)
• Event Extraction: Convert platform-specific events to unified format
• Action Execution: Execute actions like sending messages, managing groups

3. Account Layer

• Account Instances: Manage individual bot accounts
• Status Management: Track account online/offline status
• Protocol Binding: Bind accounts to specific protocols

4. Protocol Layer

• Protocol Implementations: Implement standard protocols (OneBot V11/V12, Satori, etc.)
• API Endpoints: Provide HTTP and WebSocket APIs
• Event Conversion: Convert unified events to protocol-specific formats

Client Components

1. ImHelper

• Unified Interface: Provides a unified API regardless of protocol
• Message Conversion: Converts protocol-specific messages to unified format
• Event Handling: Handles events from different protocols

2. Receivers

• WebSocket Receiver: Real-time event reception via WebSocket
• Webhook Receiver: Event reception via HTTP webhook
• SSE Receiver: Event reception via Server-Sent Events

3. Protocol Adapters

• OneBot V11 Adapter: Client SDK for OneBot V11 protocol
• OneBot V12 Adapter: Client SDK for OneBot V12 protocol
• Satori Adapter: Client SDK for Satori protocol
• Milky Adapter: Client SDK for Milky protocol

Data Flow

Server-Side Flow

1. Platform Event → Adapter receives event from platform
2. Event Conversion → Adapter converts to unified format
3. Account Processing → Account instance processes event
4. Protocol Conversion → Protocol layer converts to protocol-specific format
5. API Response → Returns to client via HTTP/WebSocket

Client-Side Flow

1. Connect → Client connects to server via WebSocket/Webhook/SSE
2. Receive Event → Receiver receives protocol-specific event
3. Protocol Adapter → Protocol adapter converts to unified format
4. ImHelper → ImHelper provides unified interface
5. Application → Application handles events and sends actions

Design Principles

1. Separation of Concerns: Clear separation between adapters, protocols, and applications
2. Unified Interface: Consistent API across different platforms and protocols
3. Extensibility: Easy to add new platforms and protocols
4. Type Safety: Full TypeScript support for better development experience
5. Modularity: Each component is independent and can be used separately