# matter-js/matterjs-server architecture

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

- Interactive diagram: https://gitdiagram.com/matter-js/matterjs-server
- Repository: https://github.com/matter-js/matterjs-server

## Overview

This repository provides a matter.js-based Matter controller server with a Python-compatible WebSocket API, plus client libraries and a browser dashboard. The main workflow is a Home Assistant or other client connecting over WebSocket, issuing commissioning or device commands, and receiving node and network updates. The server also supports configuration persistence, OTA uploads, custom clusters, and optional BLE proxying. Relationships among packages are documented in the README; source excerpts and the index clarify selected controller internals, but do not establish every runtime connection.

Main entry points: [`packages/matter-server/src/MatterServer.ts`](https://github.com/matter-js/matterjs-server/blob/main/packages/matter-server/src/MatterServer.ts) (Matter Server), [`packages/ws-controller/src/controller/MatterController.ts`](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/MatterController.ts) (Matter Controller), [`packages/ws-controller/src/server/WebSocketControllerHandler.ts`](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/server/WebSocketControllerHandler.ts) (WebSocket API), [`packages/ws-controller/src/controller/ControllerCommandHandler.ts`](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/ControllerCommandHandler.ts) (Device Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and API"]
  node_serverhost["Matter Server<br/>[MatterServer.ts]"]
  node_wsapi["WebSocket API"]
  node_config[("Configuration Storage<br/>[ConfigStorage.ts]")]
  node_ota["OTA Upload"]
end

subgraph group_controller["Matter Controller"]
  node_mattercontroller["Matter Controller"]
  node_commands["Device Commands"]
  node_nodes["Node Processing<br/>[NodeProcessor.ts]"]
  node_topology["Network Topology"]
  node_diagnostics["Thread Diagnostics"]
end

subgraph group_clients["Clients and Dashboard"]
  node_clientlib["WebSocket Client<br/>[client.ts]"]
  node_dashboard["Dashboard"]
end

subgraph group_extensions["Extensions"]
  node_bleproxy["BLE Proxy<br/>[BleProxyHandler.ts]"]
  node_customclusters["Custom Clusters<br/>[aqara.ts]"]
end

subgraph group_python["Python Support"]
  node_pyclient["Python Client<br/>[client.py]"]
  node_pyclusters["Python Cluster Models<br/>[ClusterObjects.py]"]
  node_tlv["TLV Codec<br/>[__init__.py]"]
end

node_ha(("Home Assistant"))
node_other(("Other API Client"))

node_ha -->|"connects to"| node_serverhost
node_other -->|"connects to"| node_serverhost
node_serverhost -->|"uses controller"| node_mattercontroller
node_serverhost -->|"serves API"| node_wsapi
node_mattercontroller -->|"uses storage"| node_config
node_wsapi -->|"routes requests"| node_mattercontroller
node_wsapi -->|"dispatches commands"| node_commands
node_mattercontroller -->|"creates handler"| node_commands
node_commands -->|"uses node processing"| node_nodes
node_mattercontroller -->|"uses topology service"| node_topology
node_mattercontroller -->|"uses diagnostics"| node_diagnostics
node_clientlib -->|"communicates over WebSocket"| node_wsapi
node_dashboard -->|"uses client library"| node_clientlib
node_serverhost -->|"provides upload"| node_ota
node_serverhost -.->|"optionally exposes proxy"| node_bleproxy
node_serverhost -->|"uses cluster extensions"| node_customclusters
node_pyclient -->|"connects by WebSocket"| node_serverhost
node_pyclient -->|"uses cluster models"| node_pyclusters
node_pyclusters -->|"serializes data"| node_tlv

click node_serverhost "https://github.com/matter-js/matterjs-server/blob/main/packages/matter-server/src/MatterServer.ts"
click node_wsapi "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/server/WebSocketControllerHandler.ts"
click node_config "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/server/ConfigStorage.ts"
click node_ota "https://github.com/matter-js/matterjs-server/blob/main/packages/matter-server/src/server/OtaUploadHandler.ts"
click node_mattercontroller "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/MatterController.ts"
click node_commands "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/ControllerCommandHandler.ts"
click node_nodes "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/NodeProcessor.ts"
click node_topology "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/NetworkTopologyService.ts"
click node_diagnostics "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/ThreadDiagnosticsService.ts"
click node_clientlib "https://github.com/matter-js/matterjs-server/blob/main/packages/ws-client/src/client.ts"
click node_dashboard "https://github.com/matter-js/matterjs-server/blob/main/packages/dashboard/src/pages/matter-dashboard-app.ts"
click node_bleproxy "https://github.com/matter-js/matterjs-server/blob/main/packages/ble-proxy/src/BleProxyHandler.ts"
click node_customclusters "https://github.com/matter-js/matterjs-server/blob/main/packages/custom-clusters/src/clusters/aqara.ts"
click node_pyclient "https://github.com/matter-js/matterjs-server/blob/main/python_client/matter_server/client/client.py"
click node_pyclusters "https://github.com/matter-js/matterjs-server/blob/main/python_client/chip/clusters/ClusterObjects.py"
click node_tlv "https://github.com/matter-js/matterjs-server/blob/main/python_client/chip/tlv/__init__.py"

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_serverhost,node_wsapi,node_config,node_ota,node_other toneBlue
class node_mattercontroller,node_commands,node_nodes,node_topology,node_diagnostics toneAmber
class node_clientlib,node_dashboard toneMint
class node_bleproxy,node_customclusters toneRose
class node_pyclient,node_pyclusters,node_tlv,node_ha toneIndigo
```

## Components

### Server and API

- [Matter Server](https://github.com/matter-js/matterjs-server/blob/main/packages/matter-server/src/MatterServer.ts): `packages/matter-server/src/MatterServer.ts`
- [WebSocket API](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/server/WebSocketControllerHandler.ts): `packages/ws-controller/src/server/WebSocketControllerHandler.ts`
- [Configuration Storage](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/server/ConfigStorage.ts): `packages/ws-controller/src/server/ConfigStorage.ts`
- [OTA Upload](https://github.com/matter-js/matterjs-server/blob/main/packages/matter-server/src/server/OtaUploadHandler.ts): `packages/matter-server/src/server/OtaUploadHandler.ts`

### Matter Controller

- [Matter Controller](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/MatterController.ts): `packages/ws-controller/src/controller/MatterController.ts`
- [Device Commands](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/ControllerCommandHandler.ts): `packages/ws-controller/src/controller/ControllerCommandHandler.ts`
- [Node Processing](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/NodeProcessor.ts): `packages/ws-controller/src/controller/NodeProcessor.ts`
- [Network Topology](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/NetworkTopologyService.ts): `packages/ws-controller/src/controller/NetworkTopologyService.ts`
- [Thread Diagnostics](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-controller/src/controller/ThreadDiagnosticsService.ts): `packages/ws-controller/src/controller/ThreadDiagnosticsService.ts`

### Clients and Dashboard

- [WebSocket Client](https://github.com/matter-js/matterjs-server/blob/main/packages/ws-client/src/client.ts): `packages/ws-client/src/client.ts`
- [Dashboard](https://github.com/matter-js/matterjs-server/blob/main/packages/dashboard/src/pages/matter-dashboard-app.ts): `packages/dashboard/src/pages/matter-dashboard-app.ts`

### Extensions

- [BLE Proxy](https://github.com/matter-js/matterjs-server/blob/main/packages/ble-proxy/src/BleProxyHandler.ts): `packages/ble-proxy/src/BleProxyHandler.ts`
- [Custom Clusters](https://github.com/matter-js/matterjs-server/blob/main/packages/custom-clusters/src/clusters/aqara.ts): `packages/custom-clusters/src/clusters/aqara.ts`

### Python Support

- [Python Client](https://github.com/matter-js/matterjs-server/blob/main/python_client/matter_server/client/client.py): `python_client/matter_server/client/client.py`
- [Python Cluster Models](https://github.com/matter-js/matterjs-server/blob/main/python_client/chip/clusters/ClusterObjects.py): `python_client/chip/clusters/ClusterObjects.py`
- [TLV Codec](https://github.com/matter-js/matterjs-server/blob/main/python_client/chip/tlv/__init__.py): `python_client/chip/tlv/__init__.py`

### Other components

- **Home Assistant**
- **Other API Client**

## Connections

- Home Assistant → Matter Server: connects to (evidence: `README.md`)
- Other API Client → Matter Server: connects to (evidence: `README.md`)
- Matter Server → Matter Controller: uses controller (evidence: `README.md`)
- Matter Server → WebSocket API: serves API (evidence: `README.md`)
- Matter Controller → Configuration Storage: uses storage (evidence: `packages/ws-controller/src/controller/MatterController.ts`)
- WebSocket API → Matter Controller: routes requests (evidence: `packages/ws-controller/src/server/WebSocketControllerHandler.ts`)
- WebSocket API → Device Commands: dispatches commands (evidence: `packages/ws-controller/src/server/WebSocketControllerHandler.ts`)
- Matter Controller → Device Commands: creates handler (evidence: `packages/ws-controller/src/controller/MatterController.ts`)
- Device Commands → Node Processing: uses node processing (evidence: `packages/ws-controller/src/controller/ControllerCommandHandler.ts`)
- Matter Controller → Network Topology: uses topology service (evidence: `packages/ws-controller/src/controller/MatterController.ts`)
- Matter Controller → Thread Diagnostics: uses diagnostics (evidence: `packages/ws-controller/src/controller/MatterController.ts`)
- WebSocket Client → WebSocket API: communicates over WebSocket (evidence: `README.md`)
- Dashboard → WebSocket Client: uses client library
- Matter Server → OTA Upload: provides upload (evidence: `README.md`)
- Matter Server → BLE Proxy: optionally exposes proxy (evidence: `README.md`)
- Matter Server → Custom Clusters: uses cluster extensions (evidence: `README.md`)
- Python Client → Matter Server: connects by WebSocket (evidence: `README.md`)
- Python Client → Python Cluster Models: uses cluster models (evidence: `python_client/matter_server/client/client.py`)
- Python Cluster Models → TLV Codec: serializes data (evidence: `python_client/chip/clusters/ClusterObjects.py`)
