Diagram systemu#

vCLU składa się z dwóch warstw: Go (infrastruktura) i Lua (logika biznesowa). Warstwa Go obsługuje sieć, szyfrowanie i operacje systemowe. Warstwa Lua to wszystko, co edytujesz – automatyzacje, sceny, integracje.

Architektura dwuwarstwowa#

graph TD
    subgraph go["Warstwa Go — infrastruktura"]
        web["Web Server<br/>Gin + REST API"]
        broker["MQTT Broker<br/>mochi-mqtt"]
        clu["Protokół CLU<br/>UDP + AES-128"]
        gpio["GPIO Controller<br/>RPi / Mock"]
        hk["HomeKit Bridge"]
        mcp["MCP Server"]
        plugins["Plugin Loader"]
        config["Config Manager<br/>.vclu.json"]
        ac["Access Control<br/>profile-based"]
        metrics["Metrics Collector"]
    end

    subgraph lua["Warstwa Lua — logika biznesowa"]
        vm["gopher-lua VM"]
        modules["modules/<br/>Twoje automatyzacje"]
        om["om.lua / user.lua<br/>konfiguracja obiektów"]
        eventbus["EventBus / StateBus<br/>system zdarzeń"]
        registry["Registry<br/>rejestr urządzeń"]
    end

    subgraph ext["Zewnętrzne"]
        mqtt_dev["Urządzenia MQTT"]
        grenton["Grenton CLU"]
        apple["Apple Home"]
        ha["Home Assistant"]
        ai["Agent AI"]
        browser["Przeglądarka"]
    end

    browser --> web
    web --> vm
    mqtt_dev --> broker
    broker --> vm
    grenton --> clu
    clu --> vm
    apple --> hk
    hk --> vm
    ai --> mcp
    mcp --> vm
    gpio --> vm
    vm --> modules
    vm --> om
    modules --> eventbus
    eventbus --> registry
    plugins --> vm
    config --> ac

Co robi każda warstwa#

Warstwa Go (nie edytujesz)#

Komponent	Odpowiedzialność
Web Server	Panel webowy, REST API, serwowanie plików statycznych
MQTT Broker	Wbudowany broker MQTT (mochi-mqtt), komunikacja z urządzeniami
Protokół CLU	Szyfrowana komunikacja UDP z modułami Grenton (AES-128)
GPIO Controller	Obsługa pinów Raspberry Pi (wejścia/wyjścia cyfrowe)
HomeKit Bridge	Integracja z Apple Home – automatyczna rejestracja urządzeń
MCP Server	Endpoint dla agentów AI (Claude, GPT)
Plugin Loader	Ładowanie pluginów Lua z izolowanym sandboxem
Config Manager	Zarządzanie konfiguracją `.vclu.json`
Access Control	Profile dostępu – kto co może czytać i sterować
Metrics Collector	Zbieranie metryk systemowych (CPU, pamięć, Lua, MQTT)

Warstwa Lua (edytujesz)#

Komponent	Odpowiedzialność
`modules/`	Twoje automatyzacje, sceny, integracje
`om.lua`	Definicje obiektów (generowane przez OM Grenton)
`user.lua`	Konfiguracja użytkownika (MQTT, obiekty wirtualne)
EventBus	Propagacja zdarzeń między komponentami
StateBus	Powiadamianie integracji o zmianach stanu
Registry	Centralny rejestr wszystkich urządzeń

Przepływ danych#

sequenceDiagram
    participant D as Urządzenie
    participant M as MQTT Broker
    participant E as EventBus (Lua)
    participant A as Automatyzacja
    participant S as StateBus
    participant I as Integracje

    D->>M: Publikacja stanu
    M->>E: Zdarzenie MQTT
    E->>A: Callback onChange
    A->>A: Logika (np. włącz światło)
    A->>S: Zmiana stanu obiektu
    S->>I: Dashboard / HomeKit / HA

Typowy scenariusz:

Urządzenie publikuje zmianę stanu przez MQTT (lub UDP dla Grenton)
MQTT Broker przekazuje wiadomość do warstwy Lua
EventBus wywołuje zarejestrowane callbacki
Automatyzacja reaguje na zdarzenie (np. włącza światło, wysyła powiadomienie)
StateBus automatycznie informuje wszystkie integracje o nowym stanie
Dashboard, HomeKit i Home Assistant aktualizują się bez dodatkowego kodu

Struktura katalogów#

cmd/vclu/              # punkt wejścia binarki
pkg/
  lua/                 # Lua VM + bindingi Go
    runtime/           # pliki runtime Lua
  web/                 # serwer web, REST API
  mcp/                 # serwer MCP dla agentów AI
  server/              # protokół UDP Grenton
  homekit/             # most Apple HomeKit
  broker/              # wbudowany broker MQTT
  plugins/             # loader pluginów + sandbox
  config/              # zarządzanie .vclu.json
  accesscontrol/       # kontrola dostępu oparta na profilach
  stats/               # metryki i statystyki
  gpio/                # GPIO Raspberry Pi
web/
  templates/           # szablony HTML
  static/              # JavaScript, CSS
  locales/             # tłumaczenia (en, pl)
deploy/                # systemd, skrypty instalacyjne

Kluczowe decyzje architektoniczne#

Jeden proces, zero zależności. vCLU to pojedynczy plik binarny (~13 MB) bez zewnętrznych baz danych, brokerów czy kontenerów. Broker MQTT, serwer web i runtime Lua działają w ramach jednego procesu.

Lua dla logiki, Go dla infrastruktury. Kod użytkownika jest w Lua – bezpiecznym, prostym języku, który wykonuje się w sandboxie. Cała infrastruktura sieciowa i systemowa jest w Go – szybkim, kompilowanym języku z natywnym wsparciem dla wielozadaniowości.

Kolejka zadań. Mimo że Go obsługuje wiele rzeczy jednocześnie (MQTT, HTTP, GPIO, timery), kod Lua wykonuje się sekwencyjnie – jeden callback po drugim. Dzięki temu automatyzacje są bezpieczne i przewidywalne. Szczegóły w rozdziale Wielozadaniowość.