# openimsdk/openim-sdk-core architecture

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

- Interactive diagram: https://gitdiagram.com/openimsdk/openim-sdk-core
- Repository: https://github.com/openimsdk/openim-sdk-core

## Overview

##### Project type and purpose
- This is a **cross-platform SDK core** implemented in Go.
- It provides IM networking (HTTP/WebSocket), message encoding/decoding, local storage, synchronization, and callback management.
- It targets multiple platforms via direct Go builds (Windows/MacOS/Linux), GoMobile for iOS/Android, and WebAssembly (wasm).

##### Top-level structure & architectural patterns
- **internal/**: Domain modules (conversation_msg, group, relation, user, third, interaction). Each module handles its own API calls, data conversion, sync logic, and notifications.
- **pkg/**: Shared infrastructure—network clients, DB helpers, cache, syncers, common utilities, config, error handling, version management.
- **wasm/**: WebAssembly target—cmd (entrypoint), event_listener (JS callbacks), exec, indexdb (client-side storage models), wasm_wrapper (JS bindings).
- **open_im_sdk/** & **open_im_sdk_callback/**: Language-specific bindings/callers and callback client for mobile/desktop wrappers.
- **test/** & **integration_test/** & **msgtest/**: Test clients simulating app behavior; demonstrate SDK usage and validate interfaces.

##### Core components
a. **SDK Core** (Go)
- internal modules: Conversation, Group, Relation, User, Third-party files, Interaction (long-conn & WS manager)
- pkg infra: Network (HTTP & WS client), DB layer (SQLite via pkg/db), Cache (in-memory caches), Syncer (state machine), Utils
b. **Platform Wrappers**
- GoMobile bindings (iOS/Android) & C-API via open_im_sdk/…
- WebAssembly layer (wasm/cmd → wasm_wrapper → JS)
c. **External Services**
- OpenIM Server APIs (HTTP REST + WebSocket)
- Local persistence (SQLite for native, IndexedDB for WebAssembly)
d. **Test Clients**
- Unit tests (test/)
- Integration tests (integration_test/)
- msgtest load/pressure modules

##### Relationships & data flows
- **Initialization**: load config → establish WS + HTTP connections (pkg/cliconf → pkg/network → internal/interaction).
- **Message send/receive**:
- App call → open_im_sdk (binding) → internal API (e.g., internal/conversation_msg) → network layer → server
- Server push → WS client → interaction module → dispatch to appropriate internal module → invoke callbacks (open_im_sdk_callback)
- **Sync & persistence**:
- On login or reconnection → syncer invokes internal modules → fetch from server → pkg/db persists → pkg/cache updates
- **WebAssembly**: same flows but route through wasm_wrapper and store data in IndexedDB.

##### Architectural patterns & principles
- **Modular layering**: “internal” for domain logic, “pkg” for shared infra.
- **Adapter/Decorator**: pkg/sdk_params_callback for converting between Go structs and platform-specific callback formats.
- **Stateful syncer**: pkg/syncer drives full/incremental sync workflows.
- **Observer/Callback**: subscription model in internal/interaction and open_im_sdk_callback.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "SDK Core (Go)"
        subgraph "Domain Modules"
            Conv["internal/conversation_msg"]:::core
            Group["internal/group"]:::core
            Rel["internal/relation"]:::core
            User["internal/user"]:::core
            Third["internal/third"]:::core
            Interact["internal/interaction"]:::core
        end
        subgraph "Infrastructure Modules"
            Conf["pkg/cliconf"]:::core
            Net["pkg/network"]:::core
            DB["pkg/db"]:::core
            DBi["pkg/db/db_interface"]:::core
            DBjs["pkg/db/db_js.go"]:::core
            Cache["pkg/cache"]:::core
            Sync["pkg/syncer"]:::core
            Common["pkg/common"]:::core
            Utils["pkg/utils"]:::core
            Params["pkg/sdk_params_callback"]:::core
            Errs["pkg/sdkerrs"]:::core
            APIParams["pkg/server_api_params"]:::core
            Ver["pkg/version"]:::core
        end
    end

    subgraph "Platform Wrappers"
        GO["open_im_sdk"]:::wrappers
        CB["open_im_sdk_callback"]:::wrappers
        WasmCmd["wasm/cmd"]:::wrappers
        Ev["wasm/event_listener"]:::wrappers
        Exec["wasm/exec"]:::wrappers
        IDBModel["wasm/indexdb"]:::wrappers
        WW["wasm/wasm_wrapper"]:::wrappers
    end

    subgraph "External Services"
        Serv["OpenIM Server\n(REST & WebSocket)"]:::external
        SQLite["SQLite"]:::external
        IDB["IndexedDB"]:::external
    end

    subgraph "Test Clients" 
        UT["test/"]:::test
        IT["integration_test/"]:::test
        MT["msgtest/"]:::test
    end

    %% Relationships
    GO -->|bindings| Conv
    GO -->|callbacks| Interact
    CB -->|callback client| Interact

    WasmCmd --> WW
    Ev --> WW
    Exec --> WW
    WW --> Conv
    WW -->|store| IDBModel
    IDBModel -->|persist| IDB

    Conv -->|uses| Net
    Interact -->|ws connect| Net
    Net -->|HTTP REST| Serv
    Serv -->|WebSocket Push| Interact

    Conv -->|persist| DB
    DB -->|interface| DBi
    DB -->|js db| DBjs
    DB -->|cache update| Cache
    Sync -->|sync workflows| Conv
    Sync -->|db sync| DB

    Conf -->|load config| Net
    Params -->|adapt| GO
    Errs -->|errors| Conv
    APIParams -->|api structs| Net
    Ver -->|version| GO

    UT --> Conv
    IT --> Conv
    MT --> Conv

    classDef core fill:#D0E8FF,stroke:#0366d6;
    classDef wrappers fill:#D0FFD8,stroke:#22863a;
    classDef external fill:#FFE0B2,stroke:#bf5b03;
    classDef test fill:#ECECEC,stroke:#6a737d;

    %% Click Events
    click Conv "https://github.com/openimsdk/openim-sdk-core/tree/main/internal/conversation_msg"
    click Group "https://github.com/openimsdk/openim-sdk-core/tree/main/internal/group"
    click Rel "https://github.com/openimsdk/openim-sdk-core/tree/main/internal/relation"
    click User "https://github.com/openimsdk/openim-sdk-core/tree/main/internal/user"
    click Third "https://github.com/openimsdk/openim-sdk-core/tree/main/internal/third"
    click Interact "https://github.com/openimsdk/openim-sdk-core/tree/main/internal/interaction"
    click Net "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/network"
    click DB "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/db"
    click DBi "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/db/db_interface"
    click DBjs "https://github.com/openimsdk/openim-sdk-core/blob/main/pkg/db/db_js.go"
    click Cache "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/cache"
    click Sync "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/syncer"
    click Conf "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/cliconf"
    click Common "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/common"
    click Utils "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/utils"
    click Params "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/sdk_params_callback"
    click Errs "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/sdkerrs"
    click APIParams "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/server_api_params"
    click Ver "https://github.com/openimsdk/openim-sdk-core/tree/main/pkg/version"
    click GO "https://github.com/openimsdk/openim-sdk-core/tree/main/open_im_sdk"
    click CB "https://github.com/openimsdk/openim-sdk-core/tree/main/open_im_sdk_callback"
    click WasmCmd "https://github.com/openimsdk/openim-sdk-core/tree/main/wasm/cmd"
    click Ev "https://github.com/openimsdk/openim-sdk-core/tree/main/wasm/event_listener"
    click Exec "https://github.com/openimsdk/openim-sdk-core/tree/main/wasm/exec"
    click IDBModel "https://github.com/openimsdk/openim-sdk-core/tree/main/wasm/indexdb"
    click WW "https://github.com/openimsdk/openim-sdk-core/tree/main/wasm/wasm_wrapper"
    click UT "https://github.com/openimsdk/openim-sdk-core/tree/main/test/"
    click IT "https://github.com/openimsdk/openim-sdk-core/tree/main/integration_test/"
    click MT "https://github.com/openimsdk/openim-sdk-core/tree/main/msgtest/"
```
