# matrix-org/matrix-rust-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/matrix-org/matrix-rust-sdk
- Repository: https://github.com/matrix-org/matrix-rust-sdk

## Overview

##### Main Components
- High-Level Client Library (“matrix-sdk”): This crate packages most of the client features and acts as the entry point for users of the SDK.
- Core Client State Machine (“matrix-sdk-base”): Represents the fundamental state handling logic without direct network I/O, which is used as the building block for full-fledged clients.
- Encryption Component (“matrix-sdk-crypto”): Encapsulates end-to-end encryption support, handling backups, group sessions, and cryptographic operations.
- Common and Shared Utilities (“matrix-sdk-common”, “matrix-sdk-ui”, etc.): These include shared functionality, utilities for UI synchronization, event caching, notification handling, and room management.
- Storage Implementations: There are several storage backends (for example, using SQLite in “matrix-sdk-sqlite”, IndexedDB in “matrix-sdk-indexeddb”, and store encryption in “matrix-sdk-store-encryption”) that are designed to handle persistence and caching.
- Bindings: The “bindings” directory provides wrappers for integration with non-Rust environments (e.g., Swift, Kotlin, FFI bindings).
- Examples and Labs: Sample apps and proofs-of-concept (like “autojoin”, “command_bot”, etc.) which serve as practical demonstration of how to use the SDK.
- Testing Infrastructure: Integration tests, benchmarks, and test utilities (in directories like “testing”, “benchmarks”, and under “crates/matrix-sdk/tests”) that ensure reliability and correctness.

##### Representing Relationships and Interactions
- That the high-level client interacts with external Matrix servers via RESTful API calls encapsulated in an HTTP client layer.
- For bindings, show them as adapter layers that expose the core SDK functionality to other programming environments.
- Integration modules such as “matrix-sdk-ui” which builds on top of the core client to provide UI-centric event handling, notification, and timeline management.

##### Architectural Patterns & Principles
- Separation of concerns: each crate or module has a clear responsibility (e.g., core state handling, encryption, storage, network communication, and UI).
- Layered design where higher-level APIs (the user-facing client “matrix-sdk”) are built on lower-level foundations (“matrix-sdk-base”, “matrix-sdk-crypto”).
- Plug-in potential where different storage backends or bindings can be swapped or extended based on deployment needs.

##### Relevant Technologies and Frameworks
- That the project leverages CI/CD (via the GitHub workflows) and has extensive tests and benchmarks for performance tuning.
- How the HTTP client and network communication are abstracted; even if not explicitly visible in the file tree, the README and file structure suggest a separation between network I/O and internal state management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core SDK"
        MClient["Matrix Client (matrix-sdk)"]:::core
        MBase["Core State Machine (matrix-sdk-base)"]:::core
        MCommon["Common Utilities (matrix-sdk-common)"]:::core
    end

    subgraph "Encryption Layer"
        MCrypto["Encryption Component (matrix-sdk-crypto)"]:::encryption
    end

    subgraph "UI Integrations"
        MUI["UI Integrations (matrix-sdk-ui)"]:::ui
    end

    subgraph "Storage Layer"
        SQLite["SQLite Storage (matrix-sdk-sqlite)"]:::storage
        IndexedDB["IndexedDB Storage (matrix-sdk-indexeddb)"]:::storage
        StoreEnc["Store Encryption (matrix-sdk-store-encryption)"]:::storage
    end

    subgraph "External Interfaces"
        HTTP["HTTP Client (REST API)"]:::external
        Bindings["Language Bindings (bindings)"]:::external
    end

    subgraph "Extras"
        Examples["Examples & Sample Applications (examples)"]:::extra
        Labs["Labs (labs)"]:::extra
        Testing["Testing Infrastructure (testing)"]:::extra
    end

    MClient --> MBase
    MClient --> MCommon
    MClient --> MCrypto
    MClient --> HTTP
    MClient --> Bindings
    MClient --> MUI
    MClient --> SQLite
    MClient --> IndexedDB
    MCrypto --> StoreEnc
    MCommon --> MUI
    MClient --> Examples
    MClient --> Labs
    MClient --> Testing
    MCrypto --> SQLite
    MCrypto --> IndexedDB

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef encryption fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef ui fill:#EE82EE,stroke:#000,stroke-width:2px;
    classDef storage fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef extra fill:#FFC0CB,stroke:#000,stroke-width:2px;

    click MClient "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk"
    click MBase "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-base"
    click MCrypto "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-crypto"
    click MCommon "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-common"
    click MUI "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-ui"
    click SQLite "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-sqlite"
    click IndexedDB "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-indexeddb"
    click StoreEnc "https://github.com/matrix-org/matrix-rust-sdk/tree/main/crates/matrix-sdk-store-encryption"
    click Bindings "https://github.com/matrix-org/matrix-rust-sdk/tree/main/bindings"
    click Examples "https://github.com/matrix-org/matrix-rust-sdk/tree/main/examples"
    click Labs "https://github.com/matrix-org/matrix-rust-sdk/tree/main/labs"
    click Testing "https://github.com/matrix-org/matrix-rust-sdk/tree/main/testing"
```
