# bitprince/box-im architecture

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

- Interactive diagram: https://gitdiagram.com/bitprince/box-im
- Repository: https://github.com/bitprince/box-im

## Overview

##### Main System Components
- im-platform: This is the business service layer (built with Spring Boot) that handles user login, friend/group management, API endpoints, and other HTTP-based business requests.
- im-server: A dedicated messaging push service built with Netty. It manages websocket connections, processes message push events, and handles cross-node delivery via a Redis message queue.
- im-client: The messaging SDK that other services can integrate to communicate with the im-server.
- im-common: The common package that provides shared constants, models, enums, utilities, MQ configuration, and serialization tools used by other backend modules.
- im-web: The Vue-based web client that users interact with.
- im-uniapp: The uniapp client that supports mobile platforms (native app, H5, and even WeChat mini program).
- Database, Redis, and Minio: External systems include MySQL (for persistent data storage), Redis (for inter-server messaging and queue management where keys like im:unread:{serverid} are used), and Minio (for file storage services).

##### Out Relationships and Interaction Flows
- Clients (im-web and im-uniapp) send HTTP requests (and open websocket connections) to im-platform and im-server respectively.
- The im-platform service acts as the entry point for business interactions (login, message sending, etc.). When a message is sent, it determines the target im-server based on which server the recipient is connected to.
- im-platform then places the message onto a Redis queue (using keys such as im:unread:${serverid}) dedicated to that specific im-server.
- Each im-server instance listens to its own Redis queue and pushes messages to its connected users via websocket channels.
- The im-client SDK abstracts the communication details so that other services can integrate messaging functionalities.
- im-common supports all backend components with shared classes, utilities, and MQ (message queue) handling.
- Configuration files in each module (such as application.yml, pom.xml, and various spring configuration classes) enable proper setup of each individual component.

##### Architectural Patterns and Design Principles
- Modular separation: Each module is clearly responsible for a separate part of the system (business logic, messaging, client interface).
- Asynchronous communication: The use of a Redis-backed message queue enables cross-node message push, decoupling the sending and delivery processes.
- Microservice-oriented development: Although all modules might be deployed together (or in a cluster), they are independently built and deployed.
- Separation of concerns: With im-platform handling HTTP business logic and im-server handling real-time message push, the system maintains clear boundaries for different types of functionality.

##### Relevant Technologies
- Backend: Spring Boot (im-platform, im-common), Netty (im-server), Redis (message queue and session mapping), MySQL (database), and Minio (file storage).
- Frontend: Vue (im-web) and uniapp (im-uniapp for multi-platform mobile clients).
- Communication: Websockets for realtime message push between im-server and clients; RESTful APIs for business interactions with im-platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Interfaces
    subgraph "Client Interfaces"
        WEB["im-web (Vue client)"]:::frontend
        UNIAPP["im-uniapp (uniapp mobile client)"]:::frontend
    end

    %% Business Service Layer
    subgraph "Business Service Layer"
        PLATFORM["im-platform (Spring Boot)"]:::backend
    end

    %% Shared Modules
    subgraph "Shared Modules"
        COMMON["im-common (Shared Utilities, Models, MQ)"]:::common
    end

    %% Messaging Services
    subgraph "Messaging Services"
        SERVER["im-server (Netty-based)"]:::backend
        CLIENT["im-client (Messaging SDK)"]:::sdk
    end

    %% External Systems
    subgraph "External Systems"
        MYSQL["MySQL (Database)"]:::external
        REDIS["Redis (Queue&Session)"]:::external
        MINIO["Minio (File Storage)"]:::external
    end

    %% Data flows
    WEB -->|"HTTP/API"| PLATFORM
    UNIAPP -->|"HTTP/API"| PLATFORM

    PLATFORM -->|"PushMessage:im:unread:{serverid}"| REDIS
    PLATFORM -->|"CRUD"| MYSQL
    PLATFORM -->|"FileOps"| MINIO
    PLATFORM -->|"Uses"| COMMON

    REDIS -->|"ConsumeMessages"| SERVER
    SERVER -->|"Uses"| COMMON
    SERVER -->|"WebSocketPush"| WEB
    SERVER -->|"WebSocketPush"| UNIAPP

    CLIENT -->|"IntegratesWith"| SERVER

    %% Click Events
    click PLATFORM "https://github.com/bitprince/box-im/tree/master/im-platform"
    click SERVER "https://github.com/bitprince/box-im/tree/master/im-server"
    click CLIENT "https://github.com/bitprince/box-im/tree/master/im-client"
    click COMMON "https://github.com/bitprince/box-im/tree/master/im-common"
    click WEB "https://github.com/bitprince/box-im/tree/master/im-web"
    click UNIAPP "https://github.com/bitprince/box-im/tree/master/im-uniapp"

    %% Styles
    classDef frontend fill:#D9EAD3,stroke:#333,stroke-width:2px;
    classDef backend fill:#CFE2F3,stroke:#333,stroke-width:2px;
    classDef external fill:#FCE5CD,stroke:#333,stroke-width:2px;
    classDef sdk fill:#EAD1DC,stroke:#333,stroke-width:2px;
    classDef common fill:#FFF2CC,stroke:#333,stroke-width:2px;
```
