How matrix-org/matrix-js-sdk works
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: client.ts MatrixClient · room.ts Room model · rust-crypto/index.ts Rust crypto · http-api/index.ts HTTP API
Components 24
Public API
Entry points and the main client façade exposed to consumers.
- SDK entry · Primary package exports and public surface.
src/index.ts - Browser entry · Browser-specific entry point.
src/browser-index.ts - Matrix facade · Legacy or convenience wrapper around the client API.
src/matrix.ts - MatrixClient · 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 · Typed event-emitter boundary used by client-facing APIs.
src/models/typed-event-emitter.ts - Room model · Room state, summary, receipts, and local behavior.
src/models/room.ts - Timeline · Event ordering and timeline windows.
src/models/event-timeline.ts - Room state · Aggregates membership and state events into room state.
src/models/room-state.ts - User model · User and profile state.
src/models/user.ts
Protocol Flows
Network and protocol layers for sync, auth, rendezvous, and notifications.
- HTTP API · Low-level request construction, auth refresh, prefix handling, fetch integration, and errors.
src/http-api/index.ts - Sync engine · Classic /sync ingestion and incremental state flow.
src/sync.ts - Sliding Sync · Alternative sync path for room list and timeline updates.
src/sliding-sync.ts - OIDC login · OpenID Connect discovery, auth, registration, token refresh, and validation.
src/oidc/index.ts - UIA flows · Interactive authentication flows used by Matrix endpoints.
src/interactive-auth.ts - Rendezvous · QR and secure-channel bootstrap flows for sign-in or onboarding.
src/rendezvous/index.ts - Push & receipts · 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 · Client state persistence backends for memory, local storage, IndexedDB, and worker/remote modes.
src/store/index.ts - Crypto API · Public crypto-facing API and event surface.
src/crypto-api/index.ts - Rust crypto · WASM-backed end-to-end encryption implementation and request processing.
src/rust-crypto/index.ts - Crypto store · Crypto persistence backends for key material, device state, and encrypted account data.
src/crypto/store/base.ts
RTC
Calling and MatrixRTC session orchestration.
Other components
- Homeserver · Matrix homeserver APIs for sync, rooms, media, auth, and account flows.
- WASM crypto · matrix-rust-sdk-crypto-wasm-backed crypto runtime.
Connections 28
- 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.