# wireapp/wire-apps-jvm-sdk architecture

> Architecture diagram of the GitHub repository wireapp/wire-apps-jvm-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wireapp/wire-apps-jvm-sdk
- Repository: https://github.com/wireapp/wire-apps-jvm-sdk

## Overview

##### Project Type & Purpose
- This is a Kotlin/JVM SDK (wire-apps-jvm-sdk) that third-party applications use to connect to the Wire backend as if they were regular Wire clients.

A. Bot Application
- Your custom bot code (e.g., implementing `WireEventsHandler`)
- Calls into the SDK to initialize, send messages, and receive callbacks.
B. Wire JVM SDK
1. Configuration Module
- Reads environment variables or properties (e.g., APP_TOKEN, user credentials, environment).
2. Networking Module (BackendClient)
- `BackendClientImpl` or `BackendClientDemo`
- Sends authenticated HTTP/gRPC calls to the Wire Application API.
3. Crypto Module (CryptoClient, CoreCryptoClient)
- Encrypts outbound messages and decrypts inbound messages.
- Manages key storage on the filesystem.
4. Persistence Module (SQLDelight + SQLite)
- Stores application state: conversations, teams, messages, keys.
5. Service & Router Module (WireApplicationManager, EventsRouter)
- Maintains long-polling or streaming connections.
- Routes incoming events to your `WireEventsHandler`.
C. Wire Backend Services (external)
- Wire Application API endpoints (authentication, messaging, event stream).
D. Local Storage
- Filesystem directory (e.g., `storage/apps.db`, key files).

##### Relationships & Data Flows
- Initialization Flow
1. Bot App → SDK Configuration: supply credentials/API token.
2. SDK Networking → Wire Backend: authenticate and open event stream.
3. SDK Crypto & Persistence: store keys and initial state.
- Event Handling Flow
1. Wire Backend → SDK Service: pushes encrypted events (messages, invites).
2. SDK Crypto: decrypts events.
3. SDK Persistence: persists event data.
4. SDK EventsRouter → Bot App: invokes your event handler callbacks.
- Outbound Message Flow
1. Bot App → SDK Service API: call sendMessage().
2. SDK Crypto: encrypt message payload.
3. SDK Networking → Wire Backend: HTTP/gRPC call to post message.
4. SDK Persistence: save sent message in local store.

##### Architectural Patterns & Principles
- Modular separation: configuration, networking, crypto, persistence, routing.
- Dependency injection via Koin (isolated context).
- Layered event-driven approach: network layer emits events → router layer dispatches → application code handles.
- Pluggable BackendClient (demo vs. production).
- Local first: use SQLite for offline resilience.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bot Application Zone
    subgraph "Bot Application" 
        direction TB
        JavaSample["Java Sample\n(com.wire.sdk.sample)"]:::bot
        KotlinSample["Kotlin Sample\n(com.wire.sdk.sample)"]:::bot
    end

    %% SDK Zone
    subgraph "Wire JVM SDK"
        direction TB
        Configuration["Configuration Module"]:::sdk
        Networking["Networking Module\n(BackendClient)"]:::sdk
        Crypto["Crypto Module"]:::sdk
        Persistence["Persistence Module\n(SQLDelight + SQLite)"]:::sdk
        ServiceRouter["Service & Router Module"]:::sdk
    end

    %% External & Storage Zone
    subgraph "External & Local Storage"
        direction TB
        Backend["Wire Backend Services"]:::external
        LocalStorage["Local Storage\n(filesystem)"]:::storage
    end

    %% Flows
    JavaSample -->|"supply credentials"| Configuration
    KotlinSample -->|"supply credentials"| Configuration

    Configuration -->|"authenticate"| Networking
    Networking -->|"authenticate"| Backend
    Backend -->|"event stream"| ServiceRouter

    ServiceRouter -->|"decrypt event"| Crypto
    Crypto -->|"persist event"| Persistence
    Persistence -->|"state updates"| ServiceRouter
    ServiceRouter -->|"invoke handler"| JavaSample
    ServiceRouter -->|"invoke handler"| KotlinSample

    JavaSample -->|"sendMessage()"| ServiceRouter
    KotlinSample -->|"sendMessage()"| ServiceRouter

    ServiceRouter -->|"encrypt message"| Crypto
    Crypto -->|"encrypted payload"| Networking
    Networking -->|"post message"| Backend
    Networking -->|"save sent message"| Persistence

    %% Click Events
    click JavaSample "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/sample/sample-java/src/main/java/com/wire/sdk/sample"
    click KotlinSample "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/sample/sample-kotlin/src/main/kotlin/com/wire/sdk/sample"
    click Configuration "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/lib/src/main/kotlin/com/wire/sdk/config"
    click Networking "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/lib/src/main/kotlin/com/wire/sdk/client"
    click Crypto "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/lib/src/main/kotlin/com/wire/sdk/crypto"
    click Persistence "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/lib/src/main/kotlin/com/wire/sdk/persistence"
    click ServiceRouter "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/lib/src/main/kotlin/com/wire/sdk/service"
    click LocalStorage "https://github.com/wireapp/wire-apps-jvm-sdk/tree/main/storage/"

    %% Styles
    classDef bot fill:#D0E8FF,stroke:#369,stroke-width:2px
    classDef sdk fill:#E0FFE0,stroke:#3A3,stroke-width:2px
    classDef external fill:#FFE0B2,stroke:#E67E22,stroke-width:2px
    classDef storage fill:#EEEEEE,stroke:#999,stroke-width:2px
```
