# home-assistant-libs/python-matter-server architecture

> Architecture diagram of the GitHub repository home-assistant-libs/python-matter-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/home-assistant-libs/python-matter-server
- Repository: https://github.com/home-assistant-libs/python-matter-server

## Overview

##### Project type and purpose
- This is a full-stack, controller-oriented software component (“Open Home Foundation Matter Server”) that implements a Matter Controller Server over WebSockets, plus a web-based dashboard client.
- It provides both a Python “server” (using the official Matter/CHIP SDK under the covers) and a TypeScript/JavaScript “dashboard” client that runs in a browser.
- It is designed to sit between Matter-capable devices and clients such as Home Assistant or the project’s own web dashboard, exposing device control and commissioning via a WebSockets API.

##### File structure
Top-level directories and key files:
- dashboard/ – web frontend, bundled with Rollup, TypeScript code under src/, a collection of UI components, pages, and a client library in src/client that wraps the WebSockets API.
- matter_server/ – Python package subdivided into:
– client/ – Python equivalents to the TS client library, for programmatic use
– common/ – shared constants, helper functions, JSON serializers, logging, etc.
– server/ – core server implementation: WebSocket server, client_handler, device_controller, OTA stack, storage, SDK bindings, and supporting helpers.
- main.py – entry point for launching the Python server
- Dockerfile(.dev) and docker-entrypoint.sh – containerization instructions
- scripts/ – utility scripts (e.g., code generation, environment setup)
- tests/ – unit and integration tests for both client and server modules
- docs/ – documentation for Docker setup, OS requirements, WebSockets API, etc.

##### README for additional insights
- Confirms the use of the official Matter SDK as a base.
- The server exposes a WebSockets API for clients to control devices and listen for events.
- There is both a server and a client implementation (Python and TypeScript).
- Target use case includes Home Assistant integration and standalone Docker deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Dashboard)" 
        direction TB
        Entrypoint["Dashboard Entrypoint"]:::frontend
        UI["Dashboard UI Components"]:::frontend
        ClientLibTS["Dashboard Client Library"]:::frontend
    end

    %% Backend Server
    subgraph "Backend (Python Server)" 
        direction TB
        Main["main.py"]:::backend
        WS["WebSockets API Server"]:::backend
        ClientHandler["WS API – client_handler"]:::backend
        DeviceCtrl["Device Controller"]:::backend
        subgraph "Matter SDK Bridge"
            direction TB
            SDK["sdk.py"]:::backend
            Stack["stack.py"]:::backend
        end
        subgraph "OTA Subsystem"
            direction TB
            OTAProv["OTA Provider"]:::backend
            OTADCL["OTA DCL Handlers"]:::backend
        end
        Storage["Persistent Storage"]:::storage
        Common["Common Utilities"]:::backend
        subgraph "Python Client Library"
            direction TB
            PyClient["client.py"]:::backend
            PyConn["connection.py"]:::backend
            PyModels["Client Models"]:::backend
        end
        Docker["Docker Setup"]:::external
        Scripts["Utility Scripts"]:::external
    end

    %% External Entities
    MatterDevices["Matter Devices"]:::external
    HomeAssistant["Home Assistant"]:::external

    %% Frontend to Backend communication
    ClientLibTS -->|WebSockets JSON API| WS
    WS <--> ClientLibTS

    %% External client
    HomeAssistant -->|WebSockets JSON API| WS

    %% Main entry
    Main --> WS

    %% API Layer flow
    WS --> ClientHandler
    ClientHandler --> DeviceCtrl
    DeviceCtrl --> SDK
    SDK --> MatterDevices
    MatterDevices --> SDK
    SDK --> Stack
    Stack --> MatterDevices

    %% OTA flow
    ClientHandler -->|OTA Request| OTAProv
    ClientHandler -->|OTA Request| OTADCL
    OTAProv --> SDK
    OTADCL --> SDK

    %% Storage interactions
    ClientHandler -.-> Storage
    DeviceCtrl -.-> Storage
    OTAProv -.-> Storage
    OTADCL -.-> Storage

    %% Common Utilities
    Common -.-> WS
    Common -.-> ClientHandler
    Common -.-> DeviceCtrl
    Common -.-> Storage

    %% Python client
    PyClient --> PyConn
    PyConn --> WS

    %% Click events
    click UI "https://github.com/home-assistant-libs/python-matter-server/tree/main/dashboard/src/components"
    click UI "https://github.com/home-assistant-libs/python-matter-server/tree/main/dashboard/src/pages"
    click ClientLibTS "https://github.com/home-assistant-libs/python-matter-server/tree/main/dashboard/src/client"
    click Entrypoint "https://github.com/home-assistant-libs/python-matter-server/blob/main/dashboard/src/entrypoint/main.ts"
    click WS "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/server.py"
    click ClientHandler "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/client_handler.py"
    click DeviceCtrl "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/device_controller.py"
    click SDK "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/sdk.py"
    click Stack "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/stack.py"
    click OTAProv "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/ota/provider.py"
    click OTADCL "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/ota/dcl.py"
    click Storage "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/server/storage.py"
    click Common "https://github.com/home-assistant-libs/python-matter-server/tree/main/matter_server/common/"
    click PyClient "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/client/client.py"
    click PyConn "https://github.com/home-assistant-libs/python-matter-server/blob/main/matter_server/client/connection.py"
    click PyModels "https://github.com/home-assistant-libs/python-matter-server/tree/main/matter_server/client/models/"
    click Main "https://github.com/home-assistant-libs/python-matter-server/blob/main/main.py"
    click Docker "https://github.com/home-assistant-libs/python-matter-server/tree/main/Dockerfile"
    click Docker "https://github.com/home-assistant-libs/python-matter-server/blob/main/Dockerfile.dev"
    click Docker "https://github.com/home-assistant-libs/python-matter-server/blob/main/docker-entrypoint.sh"
    click Scripts "https://github.com/home-assistant-libs/python-matter-server/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#c2f0c2,stroke:#2ca02c,stroke-width:1px
    classDef backend fill:#c2d9f8,stroke:#1f77b4,stroke-width:1px
    classDef storage fill:#fdd0a2,stroke:#ff7f0e,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#7f7f7f,stroke-width:1px
```
