# element-hq/element-web architecture

> Architecture diagram of the GitHub repository element-hq/element-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/element-hq/element-web
- Repository: https://github.com/element-hq/element-web

## Overview

Element is a Matrix web client with an Electron desktop wrapper. The principal workflow is user authentication, selecting a room, composing and dispatching messages, and exchanging Matrix events with a homeserver; encryption and key storage protect account data along the way. The graph also preserves documented desktop delivery and major client capabilities. Relationships are limited to README statements and the supplied source excerpts/index; many feature directories are unsampled, so their internal wiring is not inferred.

Main entry points: [`apps/web/src/components/structures/MatrixChat.tsx`](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/structures/MatrixChat.tsx) (Element Web), [`apps/web/src/dispatcher/dispatcher.ts`](https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/dispatcher.ts) (Action Dispatcher), [`apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx`](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx) (Encryption Settings), [`apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts`](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts) (Key Storage Logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Client"]
  node_element["Element Web<br/>[MatrixChat.tsx]"]
  node_auth["Login and Registration"]
  node_config["SDK Configuration<br/>[SdkConfig.ts]"]
  node_platform["Platform Adapter<br/>[BasePlatform.ts]"]
  node_clientcontext["Matrix Client Context"]
  node_storage["Browser Storage<br/>[StorageManager.ts]"]
  node_storageaccess["Storage Access<br/>[StorageAccess.ts]"]
end

subgraph group_messaging["Rooms and Messaging"]
  node_dispatcher["Action Dispatcher<br/>[dispatcher.ts]"]
  node_actions["Action Types<br/>[actions.ts]"]
  node_payloads["Action Payloads<br/>[payloads.ts]"]
  node_roomview["Room Timeline<br/>[RoomView.tsx]"]
  node_composer["Message Composer"]
  node_rooms["Room Features<br/>[Rooms.ts]"]
  node_eventindex["Event Search Index"]
  node_media["Media and Calls"]
end

subgraph group_security["Encryption and Settings"]
  node_encryption["Encryption Settings"]
  node_keyvm["Key Storage Logic"]
  node_deletestorage["Delete Key Storage"]
  node_device["Device Listener<br/>[DeviceListener.ts]"]
end

subgraph group_desktop["Desktop Runtime"]
  node_store[("Desktop Store<br/>[store.ts]")]
  node_desktopmain["Electron Main<br/>[electron-main.ts]"]
  node_webcontents["Web Contents Handler"]
  node_desktopconfig["Desktop Configuration<br/>[config.ts]"]
end

node_user(("User"))
node_matrixsdk["Matrix JS SDK"]
node_homeserver[("Matrix Homeserver")]
node_desktopuser(("Desktop User"))

node_user -->|"signs in"| node_auth
node_auth -.->|"enters client"| node_element
node_element -->|"uses SDK"| node_matrixsdk
node_matrixsdk -.->|"exchanges events"| node_homeserver
node_element -.->|"reads settings"| node_config
node_element -.->|"uses platform"| node_platform
node_user -.->|"opens room"| node_roomview
node_composer -->|"registers handler"| node_dispatcher
node_dispatcher -->|"uses actions"| node_actions
node_dispatcher -->|"uses payloads"| node_payloads
node_dispatcher -->|"dispatches actions"| node_composer
node_roomview -.->|"uses room logic"| node_rooms
node_user -->|"manages key storage"| node_encryption
node_encryption -->|"reads state"| node_keyvm
node_encryption -->|"opens deletion flow"| node_deletestorage
node_keyvm -->|"pauses listener"| node_device
node_deletestorage -->|"pauses listener"| node_device
node_deletestorage -->|"disables key storage"| node_matrixsdk
node_keyvm -->|"gets client"| node_clientcontext
node_matrixsdk -.->|"provides client"| node_clientcontext
node_user -.->|"searches events"| node_eventindex
node_user -.->|"uses media features"| node_media
node_storage -->|"gets IndexedDB"| node_storageaccess
node_desktopuser -.->|"launches app"| node_desktopmain
node_desktopmain -.->|"handles web contents"| node_webcontents
node_webcontents -->|"gets configuration"| node_desktopconfig
node_webcontents -.->|"uses desktop state"| node_store
node_desktopmain -->|"wraps web client"| node_element

click node_element "https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/structures/MatrixChat.tsx"
click node_auth "https://github.com/element-hq/element-web/tree/develop/apps/web/src/components/structures/auth"
click node_config "https://github.com/element-hq/element-web/blob/develop/apps/web/src/SdkConfig.ts"
click node_platform "https://github.com/element-hq/element-web/blob/develop/apps/web/src/BasePlatform.ts"
click node_dispatcher "https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/dispatcher.ts"
click node_actions "https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/actions.ts"
click node_payloads "https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/payloads.ts"
click node_roomview "https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/structures/RoomView.tsx"
click node_composer "https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/views/rooms/wysiwyg_composer/hooks/useWysiwygSendActionHandler.ts"
click node_rooms "https://github.com/element-hq/element-web/blob/develop/apps/web/src/Rooms.ts"
click node_encryption "https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx"
click node_keyvm "https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts"
click node_deletestorage "https://github.com/element-hq/element-web/blob/develop/apps/web/src/viewmodels/crypto/DeleteKeyStorageViewModel.ts"
click node_device "https://github.com/element-hq/element-web/blob/develop/apps/web/src/device-listener/DeviceListener.ts"
click node_clientcontext "https://github.com/element-hq/element-web/blob/develop/apps/web/src/contexts/MatrixClientContext.tsx"
click node_eventindex "https://github.com/element-hq/element-web/blob/develop/apps/web/src/indexing/BaseEventIndexManager.ts"
click node_media "https://github.com/element-hq/element-web/blob/develop/apps/web/src/MediaDeviceHandler.ts"
click node_storage "https://github.com/element-hq/element-web/blob/develop/apps/web/src/utils/StorageManager.ts"
click node_storageaccess "https://github.com/element-hq/element-web/blob/develop/apps/web/src/utils/StorageAccess.ts"
click node_store "https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/store.ts"
click node_desktopmain "https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/electron-main.ts"
click node_webcontents "https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/webcontents-handler.ts"
click node_desktopconfig "https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/config.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_element,node_auth,node_config,node_platform,node_clientcontext,node_storage,node_storageaccess,node_user,node_desktopuser toneBlue
class node_dispatcher,node_actions,node_payloads,node_roomview,node_composer,node_rooms,node_eventindex,node_media,node_homeserver toneAmber
class node_encryption,node_keyvm,node_deletestorage,node_device toneMint
class node_store,node_desktopmain,node_webcontents,node_desktopconfig toneRose
class node_matrixsdk toneIndigo
```

## Components

### Web Client

- [Element Web](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/structures/MatrixChat.tsx): `apps/web/src/components/structures/MatrixChat.tsx`
- [Login and Registration](https://github.com/element-hq/element-web/tree/develop/apps/web/src/components/structures/auth): `apps/web/src/components/structures/auth`
- [SDK Configuration](https://github.com/element-hq/element-web/blob/develop/apps/web/src/SdkConfig.ts): `apps/web/src/SdkConfig.ts`
- [Platform Adapter](https://github.com/element-hq/element-web/blob/develop/apps/web/src/BasePlatform.ts): `apps/web/src/BasePlatform.ts`
- [Matrix Client Context](https://github.com/element-hq/element-web/blob/develop/apps/web/src/contexts/MatrixClientContext.tsx): `apps/web/src/contexts/MatrixClientContext.tsx`
- [Browser Storage](https://github.com/element-hq/element-web/blob/develop/apps/web/src/utils/StorageManager.ts): `apps/web/src/utils/StorageManager.ts`
- [Storage Access](https://github.com/element-hq/element-web/blob/develop/apps/web/src/utils/StorageAccess.ts): `apps/web/src/utils/StorageAccess.ts`

### Rooms and Messaging

- [Action Dispatcher](https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/dispatcher.ts): `apps/web/src/dispatcher/dispatcher.ts`
- [Action Types](https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/actions.ts): `apps/web/src/dispatcher/actions.ts`
- [Action Payloads](https://github.com/element-hq/element-web/blob/develop/apps/web/src/dispatcher/payloads.ts): `apps/web/src/dispatcher/payloads.ts`
- [Room Timeline](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/structures/RoomView.tsx): `apps/web/src/components/structures/RoomView.tsx`
- [Message Composer](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/views/rooms/wysiwyg_composer/hooks/useWysiwygSendActionHandler.ts): `apps/web/src/components/views/rooms/wysiwyg_composer/hooks/useWysiwygSendActionHandler.ts`
- [Room Features](https://github.com/element-hq/element-web/blob/develop/apps/web/src/Rooms.ts): `apps/web/src/Rooms.ts`
- [Event Search Index](https://github.com/element-hq/element-web/blob/develop/apps/web/src/indexing/BaseEventIndexManager.ts): `apps/web/src/indexing/BaseEventIndexManager.ts`
- [Media and Calls](https://github.com/element-hq/element-web/blob/develop/apps/web/src/MediaDeviceHandler.ts): `apps/web/src/MediaDeviceHandler.ts`

### Encryption and Settings

- [Encryption Settings](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx): `apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx`
- [Key Storage Logic](https://github.com/element-hq/element-web/blob/develop/apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts): `apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts`
- [Delete Key Storage](https://github.com/element-hq/element-web/blob/develop/apps/web/src/viewmodels/crypto/DeleteKeyStorageViewModel.ts): `apps/web/src/viewmodels/crypto/DeleteKeyStorageViewModel.ts`
- [Device Listener](https://github.com/element-hq/element-web/blob/develop/apps/web/src/device-listener/DeviceListener.ts): `apps/web/src/device-listener/DeviceListener.ts`

### Desktop Runtime

- [Desktop Store](https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/store.ts): `apps/desktop/src/store.ts`
- [Electron Main](https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/electron-main.ts): `apps/desktop/src/electron-main.ts`
- [Web Contents Handler](https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/webcontents-handler.ts): `apps/desktop/src/webcontents-handler.ts`
- [Desktop Configuration](https://github.com/element-hq/element-web/blob/develop/apps/desktop/src/config.ts): `apps/desktop/src/config.ts`

### Other components

- **User**
- **Matrix JS SDK**
- **Matrix Homeserver**
- **Desktop User**

## Connections

- User → Login and Registration: signs in (evidence: `README.md`)
- Login and Registration → Element Web: enters client
- Element Web → Matrix JS SDK: uses SDK (evidence: `README.md`)
- Matrix JS SDK → Matrix Homeserver: exchanges events
- Element Web → SDK Configuration: reads settings
- Element Web → Platform Adapter: uses platform
- User → Room Timeline: opens room
- Message Composer → Action Dispatcher: registers handler (evidence: `apps/web/src/components/views/rooms/wysiwyg_composer/hooks/useWysiwygSendActionHandler.ts`)
- Action Dispatcher → Action Types: uses actions (evidence: `apps/web/src/dispatcher/dispatcher.ts`)
- Action Dispatcher → Action Payloads: uses payloads (evidence: `apps/web/src/dispatcher/dispatcher.ts`)
- Action Dispatcher → Message Composer: dispatches actions (evidence: `apps/web/src/components/views/rooms/wysiwyg_composer/hooks/useWysiwygSendActionHandler.ts`)
- Room Timeline → Room Features: uses room logic
- User → Encryption Settings: manages key storage (evidence: `apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx`)
- Encryption Settings → Key Storage Logic: reads state (evidence: `apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx`)
- Encryption Settings → Delete Key Storage: opens deletion flow (evidence: `apps/web/src/components/views/settings/encryption/KeyStoragePanel.tsx`)
- Key Storage Logic → Device Listener: pauses listener (evidence: `apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts`)
- Delete Key Storage → Device Listener: pauses listener (evidence: `apps/web/src/viewmodels/crypto/DeleteKeyStorageViewModel.ts`)
- Delete Key Storage → Matrix JS SDK: disables key storage (evidence: `apps/web/src/viewmodels/crypto/DeleteKeyStorageViewModel.ts`)
- Key Storage Logic → Matrix Client Context: gets client (evidence: `apps/web/src/components/viewmodels/settings/encryption/KeyStoragePanelViewModel.ts`)
- Matrix JS SDK → Matrix Client Context: provides client
- User → Event Search Index: searches events
- User → Media and Calls: uses media features
- Browser Storage → Storage Access: gets IndexedDB (evidence: `apps/web/src/utils/StorageManager.ts`)
- Desktop User → Electron Main: launches app
- Electron Main → Web Contents Handler: handles web contents
- Web Contents Handler → Desktop Configuration: gets configuration (evidence: `apps/desktop/src/webcontents-handler.ts`)
- Web Contents Handler → Desktop Store: uses desktop state
- Electron Main → Element Web: wraps web client (evidence: `README.md`)
