# matrix-org/matrix-js-sdk architecture

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

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

## Overview

1. **What this repository is**
   - `matrix-js-sdk` is a client-side SDK library for the Matrix client-server protocol, not a standalone app.
   - It targets both **browser** and **Node.js** runtimes, with a primary package entry point and a few focused sub-entry points such as `lib/crypto-api`, `lib/types`, and `lib/testing`.

2. **Top-level orchestration layer**
   - The central abstraction is the **MatrixClient** (`src/client.ts`), exposed through `src/index.ts` and `src/matrix.ts`.
   - This is the main coordination point that ties together HTTP access, sync, room/user state, crypto, notifications, and realtime features.
   - The client emits events through `EventEmitter`-style APIs, which is the main integration boundary for applications.

3. **HTTP and server communication**
   - `src/http-api/*` contains the low-level Matrix HTTP client: request construction, method/prefix handling, fetch integration, auth refresh, and error shaping.
   - Higher-level features build on this layer to talk to Matrix homeservers for sync, room operations, device management, media, OIDC, and other endpoints.
   - The README’s authenticated media note reflects a real architectural boundary: media URLs may need auth headers depending on server capabilities.

4. **Sync, incremental state, and timelines**
   - `src/sync.ts`, `src/sync-accumulator.ts`, `src/sliding-sync.ts`, and `src/sliding-sync-sdk.ts` implement the client’s main inbound data flow.
   - The SDK supports the classic Matrix `/sync` model and a separate **Sliding Sync** path for more efficient room state/timeline updates.
   - Incoming sync data is merged into room, user, receipt, and timeline state, then surfaced via events to consumers.

5. **Domain model layer**
   - `src/models/*` is the object model for Matrix concepts: `Room`, `RoomState`, `RoomMember`, `Event`, `User`, `Thread`, receipts, relations, room hierarchy, and related helpers.
   - These classes represent the SDK’s internal state graph and are the main boundary between raw server responses and application-facing objects.
   - Event ordering, local echo, room summary, and room state aggregation all live here.

6. **Persistence and storage**
   - `src/store/*` and `src/crypto/store/*` provide multiple storage backends:
     - **memory** for ephemeral use,
     - **localStorage** for limited browser persistence,
     - **IndexedDB** for durable browser storage,
     - worker/remote backends to isolate storage access.
   - The README notes that the default client store is in-memory unless configured otherwise.
   - This persistence layer is also where the crypto stack stores key material, device state, and encrypted account data.

7. **End-to-end encryption subsystem**
   - The crypto architecture is split into a public **crypto API** (`src/crypto-api/*`) and an implementation backed by **Rust/WebAssembly crypto** (`src/rust-crypto/*`).
   - The README explicitly says E2EE is based on `matrix-rust-sdk-crypto-wasm`, which is a major architectural dependency.
   - Responsibilities include device verification, secret storage, key backup, cross-signing, device dehydration, outgoing request processing, and migration from legacy crypto state.
   - This subsystem depends heavily on persistent storage and is not thread-safe across multiple clients sharing the same IndexedDB store.

8. **Realtime communication and MatrixRTC**
   - `src/webrtc/*` implements call handling, media handling, call events, group calls, and statistics collection.
   - `src/matrixrtc/*` adds higher-level MatrixRTC session and membership management, plus key transport abstractions and encryption support for RTC scenarios.
   - There is an explicit bridge to external transport concepts such as **LivekitTransport**, so the RTC stack is not just peer-to-peer WebRTC glue; it has session and transport orchestration.

9. **Identity, login, and account flows**
   - `src/oidc/*` handles OpenID Connect discovery, authorization, registration, token refresh, and validation.
   - `src/interactive-auth.ts` covers UIA-style interactive authentication flows used by Matrix endpoints.
   - These modules sit adjacent to the main client and support login/session management rather than core message sync.

10. **Rendezvous and device/user bootstrapping**
   - `src/rendezvous/*` implements QR-based or secure-channel rendezvous flows, including `MSC4108SignInWithQR`.
   - The architecture separates **transport**, **channel**, and **intent/session** layers, which suggests this is a reusable protocol stack for out-of-band connection setup.
   - This is distinct from normal sync and is used for onboarding or sign-in flows.

11. **Push, receipts, and local notifications**
   - `src/pushprocessor.ts`, `src/receipt-accumulator.ts`, `src/realtime-callbacks.ts`, and notification-related model code handle derived client behavior from incoming events.
   - This layer turns raw room events into higher-level effects like push actions, read receipts, unread counts, and local notification triggers.
   - It sits between sync ingestion and application-facing state changes.

12. **Utility, types, and compatibility boundaries**
   - `src/@types/*`, `src/utils/*`, `src/base64.ts`, `src/digest.ts`, `src/randomstring.ts`, and similar files provide shared primitives and typed Matrix protocol shapes.
   - The SDK is built in TypeScript with bundler-compatible packaging, plus browser-specific entry points like `src/browser-index.ts`.
   - This repo also preserves compatibility across many Matrix spec versions, which explains the amount of protocol modeling and feature-gating code.

13. **Quality, tests, and examples**
   - The `spec/unit` and `spec/integ` trees show a broad test split: unit tests for isolated modules and integration tests for sync, crypto, sliding sync, rendezvous, and RTC behavior.
   - `examples/node` and `examples/voip` demonstrate two main integration styles: a terminal/Node client and a browser-based calling example.
   - The CI/workflow and release tooling in `.github/*` support a mature library lifecycle: tests, static analysis, docs generation, release signing, and downstream compatibility checks.

14. **How to draw the architecture**
   - The cleanest diagram is a layered library:
     - application code on top,
     - `MatrixClient` as the orchestration core,
     - domain models and event emitters underneath,
     - transport/protocol modules for HTTP, sync, OIDC, rendezvous, and RTC,
     - storage backends and crypto persistence at the bottom,
     - with Rust/WASM crypto and Matrix homeserver services as the key external boundaries.

Main entry points: [`src/client.ts`](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/client.ts) (MatrixClient), [`src/models/room.ts`](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/room.ts) (Room model), [`src/rust-crypto/index.ts`](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/rust-crypto/index.ts) (Rust crypto), [`src/http-api/index.ts`](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/http-api/index.ts) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_index["SDK entry<br/>entrypoint<br/>[index.ts]"]
  node_browser_index["Browser entry<br/>entrypoint<br/>[browser-index.ts]"]
  node_matrix["Matrix facade<br/>[matrix.ts]"]
  node_client["MatrixClient<br/>orchestrator<br/>[client.ts]"]
end

subgraph group_state["State & Models"]
  node_typed_emitter(("Typed events<br/>event-api"))
  node_room["Room model<br/>domain model<br/>[room.ts]"]
  node_event_timeline["Timeline<br/>domain model<br/>[event-timeline.ts]"]
  node_state_model["Room state<br/>domain model<br/>[room-state.ts]"]
  node_user_model["User model<br/>domain model<br/>[user.ts]"]
end

subgraph group_protocols["Protocol Flows"]
  node_http_api["HTTP API<br/>transport<br/>[index.ts]"]
  node_sync["Sync engine<br/>state ingestion<br/>[sync.ts]"]
  node_sliding_sync["Sliding Sync<br/>state ingestion<br/>[sliding-sync.ts]"]
  node_oidc["OIDC login<br/>auth flow<br/>[index.ts]"]
  node_interactive_auth["UIA flows<br/>auth flow"]
  node_rendezvous["Rendezvous<br/>bootstrap flow<br/>[index.ts]"]
  node_push_receipts["Push & receipts<br/>derived state<br/>[pushprocessor.ts]"]
end

subgraph group_crypto["Crypto & Storage"]
  node_store[("Stores<br/>persistence<br/>[index.ts]")]
  node_crypto_api["Crypto API<br/>[index.ts]"]
  node_rust_crypto["Rust crypto<br/>e2ee implementation<br/>[index.ts]"]
  node_crypto_store[("Crypto store<br/>encrypted storage<br/>[base.ts]")]
end

subgraph group_rtc["RTC"]
  node_webrtc["WebRTC<br/>calling<br/>[call.ts]"]
  node_matrixrtc["MatrixRTC<br/>session layer<br/>[index.ts]"]
end

node_homeserver[("Homeserver<br/>external service")]
node_wasm_crypto{{"WASM crypto<br/>external dependency"}}

node_index -->|"exports"| node_client
node_browser_index -->|"browser entry"| node_client
node_matrix -->|"wraps"| node_client
node_client -->|"emits"| node_typed_emitter
node_client -->|"manages"| node_room
node_client -->|"ingests"| node_sync
node_client -->|"ingests"| node_sliding_sync
node_client -->|"requests"| node_http_api
node_client -->|"auth"| node_oidc
node_client -->|"uia"| node_interactive_auth
node_client -->|"bootstrap"| node_rendezvous
node_client -->|"derives"| node_push_receipts
node_client -->|"persists"| node_store
node_client -->|"crypto api"| node_crypto_api
node_crypto_api -->|"backed by"| node_rust_crypto
node_rust_crypto -->|"reads/writes"| node_crypto_store
node_rust_crypto -->|"depends on"| node_wasm_crypto
node_store -.->|"sync state"| node_homeserver
node_http_api -->|"calls"| node_homeserver
node_sync -->|"syncs"| node_homeserver
node_sliding_sync -->|"syncs"| node_homeserver
node_oidc -->|"auth endpoints"| node_homeserver
node_rendezvous -->|"sign-in"| node_homeserver
node_webrtc -->|"feeds"| node_matrixrtc
node_matrixrtc -->|"integrates"| node_client
node_room -->|"contains"| node_state_model
node_room -->|"uses"| node_event_timeline
node_room -->|"references"| node_user_model

click node_index "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/index.ts"
click node_browser_index "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/browser-index.ts"
click node_matrix "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/matrix.ts"
click node_client "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/client.ts"
click node_typed_emitter "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/typed-event-emitter.ts"
click node_room "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/room.ts"
click node_event_timeline "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/event-timeline.ts"
click node_state_model "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/room-state.ts"
click node_user_model "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/user.ts"
click node_http_api "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/http-api/index.ts"
click node_sync "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/sync.ts"
click node_sliding_sync "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/sliding-sync.ts"
click node_oidc "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/oidc/index.ts"
click node_interactive_auth "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/interactive-auth.ts"
click node_rendezvous "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/rendezvous/index.ts"
click node_push_receipts "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/pushprocessor.ts"
click node_store "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/store/index.ts"
click node_crypto_api "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/crypto-api/index.ts"
click node_rust_crypto "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/rust-crypto/index.ts"
click node_crypto_store "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/crypto/store/base.ts"
click node_webrtc "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/webrtc/call.ts"
click node_matrixrtc "https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/matrixrtc/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_browser_index,node_matrix,node_client toneBlue
class node_typed_emitter,node_room,node_event_timeline,node_state_model,node_user_model toneAmber
class node_http_api,node_sync,node_sliding_sync,node_oidc,node_interactive_auth,node_rendezvous,node_push_receipts toneMint
class node_store,node_crypto_api,node_rust_crypto,node_crypto_store toneRose
class node_webrtc,node_matrixrtc toneIndigo
class node_homeserver,node_wasm_crypto toneNeutral
```

## Components

### Public API

Entry points and the main client façade exposed to consumers.

- [SDK entry](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/index.ts): entrypoint · Primary package exports and public surface. · `src/index.ts`
- [Browser entry](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/browser-index.ts): entrypoint · Browser-specific entry point. · `src/browser-index.ts`
- [Matrix facade](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/matrix.ts): facade · Legacy or convenience wrapper around the client API. · `src/matrix.ts`
- [MatrixClient](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/client.ts): orchestrator · Main coordination point for sync, rooms, crypto, auth, and realtime features. · `src/client.ts`

### State & Models

Domain objects that hold Matrix room, user, and event state.

- [Typed events](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/typed-event-emitter.ts): event-api · Typed event-emitter boundary used by client-facing APIs. · `src/models/typed-event-emitter.ts`
- [Room model](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/room.ts): domain model · Room state, summary, receipts, and local behavior. · `src/models/room.ts`
- [Timeline](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/event-timeline.ts): domain model · Event ordering and timeline windows. · `src/models/event-timeline.ts`
- [Room state](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/room-state.ts): domain model · Aggregates membership and state events into room state. · `src/models/room-state.ts`
- [User model](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/models/user.ts): domain model · User and profile state. · `src/models/user.ts`

### Protocol Flows

Network and protocol layers for sync, auth, rendezvous, and notifications.

- [HTTP API](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/http-api/index.ts): transport · Low-level request construction, auth refresh, prefix handling, fetch integration, and errors. · `src/http-api/index.ts`
- [Sync engine](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/sync.ts): state ingestion · Classic /sync ingestion and incremental state flow. · `src/sync.ts`
- [Sliding Sync](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/sliding-sync.ts): state ingestion · Alternative sync path for room list and timeline updates. · `src/sliding-sync.ts`
- [OIDC login](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/oidc/index.ts): auth flow · OpenID Connect discovery, auth, registration, token refresh, and validation. · `src/oidc/index.ts`
- [UIA flows](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/interactive-auth.ts): auth flow · Interactive authentication flows used by Matrix endpoints. · `src/interactive-auth.ts`
- [Rendezvous](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/rendezvous/index.ts): bootstrap flow · QR and secure-channel bootstrap flows for sign-in or onboarding. · `src/rendezvous/index.ts`
- [Push & receipts](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/pushprocessor.ts): derived state · Unread counts, read receipts, push actions, and local notification effects. · `src/pushprocessor.ts`

### Crypto & Storage

Persistence backends and end-to-end encryption implementation layers.

- [Stores](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/store/index.ts): persistence · Client state persistence backends for memory, local storage, IndexedDB, and worker/remote modes. · `src/store/index.ts`
- [Crypto API](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/crypto-api/index.ts): public crypto API · Public crypto-facing API and event surface. · `src/crypto-api/index.ts`
- [Rust crypto](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/rust-crypto/index.ts): e2ee implementation · WASM-backed end-to-end encryption implementation and request processing. · `src/rust-crypto/index.ts`
- [Crypto store](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/crypto/store/base.ts): encrypted storage · Crypto persistence backends for key material, device state, and encrypted account data. · `src/crypto/store/base.ts`

### RTC

Calling and MatrixRTC session orchestration.

- [WebRTC](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/webrtc/call.ts): calling · Call handling, media handling, and group call behavior. · `src/webrtc/call.ts`
- [MatrixRTC](https://github.com/matrix-org/matrix-js-sdk/blob/develop/src/matrixrtc/index.ts): session layer · Session, membership, and transport orchestration for RTC scenarios. · `src/matrixrtc/index.ts`

### Other components

- **Homeserver**: external service · Matrix homeserver APIs for sync, rooms, media, auth, and account flows.
- **WASM crypto**: external dependency · matrix-rust-sdk-crypto-wasm-backed crypto runtime.

## Connections

- SDK entry → MatrixClient: exports · The package entry re-exports the main client surface.
- Browser entry → MatrixClient: browser entry · Browser bundle entry wires consumers to the same client core.
- Matrix facade → MatrixClient: wraps · Facade module routes to the client orchestrator.
- MatrixClient → Typed events: emits · Client communicates outward through event APIs.
- MatrixClient → Room model: manages · Client owns room objects and room-level operations.
- MatrixClient → Sync engine: ingests · Classic sync feeds the client state machine.
- MatrixClient → Sliding Sync: ingests · Sliding Sync provides an alternate inbound state stream.
- MatrixClient → HTTP API: requests · All homeserver communication builds on the HTTP layer.
- MatrixClient → OIDC login: auth · OIDC supports login and session management.
- MatrixClient → UIA flows: uia · Interactive auth handles challenge-response flows.
- MatrixClient → Rendezvous: bootstrap · Rendezvous handles QR and secure-channel onboarding.
- MatrixClient → Push & receipts: derives · Incoming events are converted into unread, receipt, and notification effects.
- MatrixClient → Stores: persists · Client state can be backed by configurable storage.
- MatrixClient → Crypto API: crypto api · Client exposes public crypto operations through the crypto API boundary.
- Crypto API → Rust crypto: backed by · Public crypto API delegates to the Rust/WebAssembly implementation.
- Rust crypto → Crypto store: reads/writes · Crypto implementation depends on durable crypto persistence.
- Rust crypto → WASM crypto: depends on · E2EE implementation is backed by the external WASM crypto runtime.
- Stores → Homeserver: sync state · Persistent client state is ultimately driven by homeserver data.
- HTTP API → Homeserver: calls · Low-level HTTP layer talks to Matrix server endpoints.
- Sync engine → Homeserver: syncs · Classic sync reads updates from the homeserver.
- Sliding Sync → Homeserver: syncs · Sliding Sync reads efficient room and timeline updates from the homeserver.
- OIDC login → Homeserver: auth endpoints · OIDC and related account flows interact with server auth endpoints.
- Rendezvous → Homeserver: sign-in · Bootstrap flows exchange data through server-mediated rendezvous.
- WebRTC → MatrixRTC: feeds · Calling primitives support MatrixRTC session orchestration.
- MatrixRTC → MatrixClient: integrates · RTC session management integrates with the main client.
- Room model → Room state: contains · Room behavior depends on room state aggregation.
- Room model → Timeline: uses · Room rendering and behavior use timelines.
- Room model → User model: references · Room membership and profile state relate to user objects.
