# crossoverjie/cim architecture

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

- Interactive diagram: https://gitdiagram.com/crossoverjie/cim
- Repository: https://github.com/crossoverjie/cim

## Overview

##### Project Type & Purpose
- Type: A modular, full‑stack distributed IM system, composed of multiple Spring Boot microservices and a lightweight CLI client.
- Purpose: Provide an extensible instant‑messaging framework (CIM) with built‑in routing, service registration/discovery, client SDK, and CLI client.

##### File Structure
- Top‑level modules (Maven subprojects):
– cim-common: shared data structures, ProtoBuf definitions, routing algorithms, MetaStore abstractions.
– cim-client-sdk: Java client SDK exposing APIs for connection, reconnect logic, event handling.
– cim-client: Spring Boot CLI client app using the SDK, handles user input/commands.
– cim-rout-api & cim-server-api: API definitions (VOs, interfaces) for route and server services.
– cim-forward-route: “Route” service—login, routing logic, user management, uses Redis cache.
– cim-server: “IM Server” service—Netty server for persistent connections, message push, heartbeat.
– cim-integration-test: integration tests wiring up route + server + client SDK.
- Infrastructure/config:
– script/…: build & deploy scripts.
– .github/workflows: CI runs Maven tests & build.
– application.yaml files per service.
– Dependencies on Zookeeper (MetaStore), Redis, Netty, Protobuf.

##### Derive Key Architecture from README
- Services register/discover via MetaStore (Zookeeper).
- Route‐service subscribes to MetaStore to get IM server list and caches in Redis.
- Client logs in via Route (HTTP/REST), then opens Netty socket to an IM server (selected via Route).
- Messages from Client→Route→IM server→Client.

##### Main Components & Their Relationships
a. Components:
1. CLI Client (cim-client)
2. Client SDK (cim-client-sdk)
3. Route Service (cim-forward-route)
4. IM Server (cim-server)
5. MetaStore (Zookeeper)
6. Redis cache (user info in Route)
7. Shared library (cim-common)
b. Interactions / Data Flow:
1. IM Server → registers itself with MetaStore on startup.
2. Route Service → subscribes to MetaStore to watch changes in server list.
3. CLI Client → HTTP Login → Route Service → stores session, returns server info.
4. CLI Client → opens Netty TCP connection → IM Server (via Client SDK)
5. CLI Client → send message → first to Route Service (JSON/HTTP or via SDK + REST)
then Route picks a server (consistent hashing/algorithm from cim‑common)
→ forwards to IM Server over HTTP or direct RPC → pushes to target Client via Netty.
6. Heartbeats and reconnection managed by SDK (ReconnectManager, BackoffStrategy).
c. Architectural Patterns:
- Modular microservices (Spring Boot per module).
- Registry/Discovery via MetaStore (Zookeeper).
- Caching/persistence of user sessions in Redis for Route.
- Netty pipeline on IM Server + Client for binary ProtoBuf payloads.
- Dynamic proxy & RPC abstraction in cim-common.
d. Key Technologies:
- Spring Boot 3.x (each module)
- Netty (network I/O)
- Protocol Buffers (.proto in cim-common)
- Zookeeper (MetaStore)
- Redis (Route cache)
- Maven multi-module structure
- Java 17
- Swagger/OpenAPI (config in each service)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        CLI["CLI Client"]:::client
        SDK["Client SDK"]:::client
        CLI -->|"uses SDK"| SDK
    end

    %% Routing Tier
    subgraph "Routing Tier"
        direction TB
        Route["Route Service"]:::service
    end

    %% Core Tier
    subgraph "Core Tier"
        direction TB
        Server["IM Server"]:::service
    end

    %% Infrastructure Tier
    subgraph "Infrastructure"
        direction TB
        ZK["MetaStore (Zookeeper)"]:::infra
        Redis["Redis Cache"]:::infra
    end

    %% Shared Library
    Common["cim-common Library"]:::common

    %% Data Flows & Dependencies
    SDK -->|"HTTP/REST Login"| Route
    SDK -->|"Netty/Protobuf"| Server
    Route -->|"cache session"| Redis
    Route -->|"subscribe/register"| ZK
    ZK -->|"notify changes"| Route
    Server -->|"register & heartbeat"| ZK
    Common --> CLI
    Common --> SDK
    Common --> Route
    Common --> Server

    %% Click Events
    click CLI "https://github.com/crossoverjie/cim/tree/master/cim-client"
    click SDK "https://github.com/crossoverjie/cim/tree/master/cim-client-sdk"
    click Route "https://github.com/crossoverjie/cim/tree/master/cim-forward-route"
    click Server "https://github.com/crossoverjie/cim/tree/master/cim-server"
    click Common "https://github.com/crossoverjie/cim/tree/master/cim-common"

    %% Styles
    classDef client fill:#b3ffb3,stroke:#008000,color:#000;
    classDef service fill:#b3d1ff,stroke:#0000ff,color:#000;
    classDef infra fill:#ffd1b3,stroke:#ff8000,color:#000;
    classDef common fill:#e5e5e5,stroke:#808080,color:#000;
```
