# rdmtc/redmatic architecture

> Architecture diagram of the GitHub repository rdmtc/redmatic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdmtc/redmatic
- Repository: https://github.com/rdmtc/redmatic

## Overview

##### Project type and purpose
- From the file tree and README we see that RedMatic is not a classic two-tier web app but an embedded “CCU Addon” that packages Node-RED, a web server (lighttpd), CCU-integration scripts, various prebuilt binaries and Node-RED nodes into a single deployable on Homematic CCU3/RaspberryMatic.
- Its purpose is to provide a visual automation layer (Node-RED) tightly integrated with Homematic CCU, plus a simple WebApp, Dashboard UI, HomeKit bridge, MQTT node, and dozens of community nodes, all running on the CCU.

##### File structure
- Top-level directories:
- addon_files/… → The layout of the CCU addon (bin/, etc/, lib/, www/, var/, tmp/, share/…).
- prebuilt/… → Binaries for multiple architectures (aarch64, armv6l, armv7l, i686, x86_64).
- assets/ → Logos and favicons.
- docs/, BUILD.md, build scripts, update scripts → Build & packaging toolchain.
- package.json → Node.js dependencies for the build tooling and possibly Node-RED defaults.
- Within addon_files/redmatic:
- bin/ → startup scripts (redmaticLoader), health checks (monit-start, checkContext…), logging and packaging utilities.
- etc/ → default JSON settings, lighttpd.conf, monit.cfg, npmrc.
- lib/ → JS and TCL libraries for CCU-Rega integration, session handling, logging.
- www/ → CGI front‐end for the WebApp, static CSS/JS, prebuilt HTML pages.
- var/ → runtime state: npm cache, example flows, restart_count.
- You see an MVC‐style split:
- Configuration (etc/)
- Runtime code (lib/, www/)
- Data and state (var/, tmp/)
- Process control (bin/, monit.cfg)

##### README for additional insights
- Confirms core components: Node-RED + CCU-Nodes, RedMatic WebApp, Node-RED Dashboard, RedMatic HomeKit, MQTT node.
- Describes add-on installation via CCU WebUI, built-in support for external services (AWS, Google Home, databases).
- Mentions a lighttpd front-end and community‐provided flows/nodes.

a. Main components
- Homematic CCU Host (CCU3 or RaspberryMatic OS)
- RedMatic Addon Container/Environment
– Process Supervisor (monit)
– Startup Script (redmaticLoader)
– Node.js Runtime & Node-RED Engine
– Custom Node-RED Nodes (CCU-Nodes, HomeKit, MQTT, Dashboard)
– TCL Modules & CCU-Rega Bridge (rega-auth.tcl, session.tcl, querystring.tcl)
– Static WebApp (lighttpd + CGI + CSS/JS)
– Data Stores: flows.json, user settings, npm cache
- Prebuilt Native Binaries (ffmpeg, coap-client, git, jq, jo, …)
- External Services
– MQTT broker
– HomeKit clients / Siri
– Third-party nodes (KNX, Hue, database, web APIs, Alexa, Google Home…)

b. Relationships and interactions
– monit → monitors redmaticLoader and Node-RED; restarts on failure
– redmaticLoader → boots Node.js, initializes settings, loads flows
– Node-RED →
- Calls CCU via TCL scripts (Rega API)
- Exposes HTTP endpoints to lighttpd (WebApp and Dashboard)
- Publishes/subscribes to external MQTT
- Serves Dashboard assets
- Interacts with Node-RED nodes for HomeKit and other services
– lighttpd →
- Serves WebApp/UI and proxies API calls to Node-RED
- Delivers preconfigured CGI scripts (log.cgi, backup.cgi…)
– Prebuilt binaries → invoked by Node-RED or bin scripts for advanced tasks (video, git operations, coap, JSON processing)

c. Architectural patterns / design principles
– Modular packaging: isolating config, binaries, libs, web assets, state
– Process supervision: using monit to ensure high availability
– Micro-services within a single container: CGI front-end + Node-RED engine + TCL bridge
– Separation of concerns:
- Networking & HTTP (lighttpd)
- Business logic / flows (Node-RED)
- Device API bridge (TCL/Rega)
- Platform packaging (addon_files layout)

d. Key technologies, frameworks, libraries
– Node.js & Node-RED core
– node-red-contrib-ccu, node-red-dashboard, various contrib nodes
– TCL scripts for Rega auth & context
– lighttpd + CGI for WebApp
– monit for process management
– Shell/Bash for build & startup
– Prebuilt C utilities (ffmpeg, git, coap-client, …)

##### Final advice
- Every critical piece: supervisory scripts, runtime engine, web server, bridge scripts, binaries, storage, external services.
- Keep labels consistent with directory names and config file names to aid traceability.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Host boundary
    subgraph "Homematic CCU3 / RaspberryMatic OS"
        direction TB
        subgraph "RedMatic Addon Container"
            direction TB

            %% Process Control Layer
            subgraph "Process Control"
                direction TB
                ProcessSupervisor["monit"]:::process
                MonitStart["monit-start"]:::process
                RedmaticLoader["redmaticLoader"]:::process
                ProcessSupervisor -->|"monitors"| MonitStart
                MonitStart -->|"starts"| RedmaticLoader
            end

            %% Runtime Engine Layer
            subgraph "Runtime Engine"
                direction TB
                NodeJSRuntime["Node.js Runtime"]:::process
                RedmaticEngine["redmatic (Node-RED Engine)"]:::process
                RedmaticLoader -->|"bootstraps"| NodeJSRuntime
                NodeJSRuntime -->|"launches"| RedmaticEngine
            end

            %% CCU-Rega Bridge
            subgraph "CCU-Rega Bridge (TCL)"
                direction TB
                RegaAuth["rega-auth.js"]:::binary
                LogTcl["log.tcl"]:::binary
                QueryTcl["querystring.tcl"]:::binary
                SessionTcl["session.tcl"]:::binary
                RedmaticEngine -->|"calls"| RegaAuth
                RedmaticEngine -->|"calls"| LogTcl
                RedmaticEngine -->|"calls"| QueryTcl
                RedmaticEngine -->|"calls"| SessionTcl
            end

            %% Custom Node-RED Nodes
            subgraph "Custom Node-RED Nodes"
                direction TB
                CCUNode["node-red-contrib-ccu"]:::process
                DashboardNode["node-red-dashboard"]:::process
                HomeKitNode["node-red-contrib-homekit"]:::process
                MQTTNode["node-red-node-mqtt"]:::process
                RedmaticEngine -->|"loads"| CCUNode
                RedmaticEngine -->|"loads"| DashboardNode
                RedmaticEngine -->|"loads"| HomeKitNode
                RedmaticEngine -->|"loads"| MQTTNode
            end

            %% WebApp Layer
            subgraph "WebApp (lighttpd + CGI)"
                direction TB
                Lighttpd["lighttpd"]:::process
                CGI["*.cgi scripts"]:::process
                CSS["style.css"]:::process
                JS["script.js"]:::process
                Lighttpd -->|"serves"| CGI
                Lighttpd -->|"serves"| CSS
                Lighttpd -->|"serves"| JS
                Lighttpd -->|"proxies API to"| RedmaticEngine
                RedmaticEngine -->|"exposes UI to"| Lighttpd
            end

            %% Data Stores
            subgraph "Data & State"
                direction TB
                Flows["example-flows.json"]:::data
                NpmCache["npm-cache"]:::data
                RestartCount["restart_count"]:::data
                RedmaticEngine -->|"reads/writes"| Flows
                RedmaticEngine -->|"uses"| NpmCache
                MonitStart -->|"increments"| RestartCount
            end

        end

        %% Prebuilt Binaries
        Prebuilt["prebuilt native binaries"]:::binary
        RedmaticEngine -->|"invokes"| Prebuilt

        %% External Services
        subgraph "External Integrations"
            direction TB
            MQTTBroker["MQTT Broker"]:::external
            HomeKitClients["HomeKit Clients / Siri"]:::external
            ThirdParty["Third-Party Services"]:::external
            RedmaticEngine -->|"pub/sub"| MQTTBroker
            RedmaticEngine -->|"bridges"| HomeKitClients
            RedmaticEngine -->|"calls"| ThirdParty
        end
    end

    %% Click Events
    click ProcessSupervisor "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/etc/monit.cfg"
    click MonitStart "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/bin/monit-start"
    click RedmaticLoader "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/bin/redmaticLoader"
    click RedmaticEngine "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/bin/redmatic"
    click NodeJSRuntime "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/lib/package.json"
    click RegaAuth "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/lib/rega-auth.js"
    click LogTcl "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/lib/log.tcl"
    click QueryTcl "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/lib/querystring.tcl"
    click SessionTcl "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/lib/session.tcl"
    click CCUNode "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/lib/node-red-contrib-ccu"
    click DashboardNode "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/lib/node-red-dashboard"
    click HomeKitNode "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/lib/node-red-contrib-homekit"
    click MQTTNode "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/lib/node-red-node-mqtt"
    click Lighttpd "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/etc/lighttpd.conf"
    click CGI "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/www"
    click CSS "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/www/css/style.css"
    click JS "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/www/js/script.js"
    click Flows "https://github.com/rdmtc/redmatic/blob/master/addon_files/redmatic/var/example-flows.json"
    click NpmCache "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/var/npm-cache/"
    click RestartCount "https://github.com/rdmtc/redmatic/tree/master/addon_files/redmatic/var/restart_count"

    %% Styles
    classDef process fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef binary fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
