# simoncoles/zigbee2mqtt-capture architecture

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

- Interactive diagram: https://gitdiagram.com/simoncoles/zigbee2mqtt-capture
- Repository: https://github.com/simoncoles/zigbee2mqtt-capture

## Overview

##### Project type and purpose
- This is a Rails-based full-stack web application whose primary function is to listen for MQTT messages (e.g., from zigbee2mqtt), store them in a database, and present them via a web UI (Madmin admin panels and basic ERB views).
- It combines a background MQTT consumer thread, a database persistence layer, and a Rails web server (Puma) exposing an admin UI and optional API endpoints.

##### File structure
- Top-level “app” directory follows Rails MVC:
- app/models – ActiveRecord models (Device, MqttMessage, Reading)
- app/controllers – standard controllers plus a namespaced Madmin controller for the admin UI
- app/views – layouts, PWA manifest, service-worker, and any ERB pages
- app/javascript – Stimulus controllers via Importmap (minimal frontend interactivity)
- config/initializers/mqtt_tasks.rb + lib hooks define and wire up the background MQTT listener (MqttMessage.listen).
- config/puma.rb, config/database.yml, Dockerfile, and .devcontainer describe deployment/build.
- db/schema.rb and db/migrate show the data model evolution (tables for messages, devices, readings, ActiveStorage blobs).
- Gemfile includes gems for Rails, Madmin, MQTT client, AppSignal, etc.

##### Readme insights
- Requires an external MQTT broker and optionally zigbee2mqtt.
- Exposes a containerized deployment (Docker, Docker Compose).
- No built-in authentication – intended for private networks.
- Environment variables configure MQTT_URL, DATABASE_URL, ZIGBEE2MQTT_BASE, PRUNE_HOURS, etc.

a. Main components
- External Systems
1. zigbee2mqtt (or any MQTT publisher)
2. MQTT Broker (e.g., Mosquitto)
3. Web Browser / Admin user
4. (Optional) External Zigbee2MQTT Web UI
- Application
1. Rails Server (Puma)
- Web UI Layer (Madmin controllers + ERB views)
- API / Service Layer (if any endpoints)
- Importmap/Stimulus frontend controllers
2. Background MQTT Listener
- MqttMessage.listen process/thread
- Subscribes to topics, parses JSON payloads
3. Database (SQLite by default, or Postgres/MySQL)
4. ActiveStorage service (local disk storage under storage/ or external blob service)
5. Optional AppSignal for error monitoring
b. Relationships and data flows
- zigbee2mqtt → publishes to → MQTT Broker
- Rails Background Listener → subscribes to → MQTT Broker
- Listener → writes to → Database
- Rails Web UI → reads from → Database
- Web Browser ↔ HTTP(S) ↔ Rails Server
- Rails Server → (optionally) link to → external Zigbee2MQTT UI using ZIGBEE2MQTT_BASE
c. Architectural patterns/principles
- MVC for web layer
- Single-process with multi-threaded work: web server threads + background listener thread
- Clear separation of concerns: message ingestion vs. persistence vs. presentation
- Containerized deployment (Docker) with 12-factor config via environment variables
d. Key technologies
- Ruby on Rails 8.0 (MVC, ActiveRecord, ActiveStorage)
- Madmin gem for admin interface
- MQTT Ruby client (embedded in initializer)
- Puma web server
- Stimulus controllers via Importmap (no Webpack)
- Docker (.devcontainer + Dockerfile + compose.yaml)

##### Detail
- Environment-driven integrations: MQTT broker connectivity, database adapter choice, optional AppSignal.
- PWA manifest/service-worker as part of static assets under “app/views/pwa”.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External systems
    subgraph "External Systems"
        Zigbee["zigbee2mqtt"]:::external
        Broker["MQTT Broker"]:::external
        Browser["Web Browser / Admin User"]:::external
        ZigUI["Zigbee2MQTT UI (Optional)"]:::external
    end

    %% Rails Application Container
    subgraph "Container: Rails Application"
        %% Background Listener
        subgraph "Rails: Background MQTT Listener"
            Listener["MqttMessage.listen"]:::appComp
        end

        %% Web Server
        subgraph "Rails: Web Server (Puma)"
            Puma["Web Server (Puma)"]:::appComp
            UI["Web UI Layer (Madmin + ERB Views)"]:::appComp
            API["Optional API Endpoints"]:::appComp
            JS["Importmap / Stimulus Controllers"]:::appComp
        end

        %% Data Stores
        DB["Database"]:::datastore
        AS["ActiveStorage Service"]:::storage

        %% Monitoring
        Monitoring["AppSignal (Optional)"]:::external
    end

    %% Relationships
    Zigbee -->|"publishes to"| Broker
    Broker -->|"subscribes to"| Listener
    Listener -->|"writes to"| DB
    Browser -->|"HTTP(S)"| Puma
    Puma -->|"reads from / writes to"| DB
    Puma -->|"serves UI"| UI
    UI -->|"uses"| JS
    Puma -->|"stores files in"| AS
    Puma -->|"reports errors to"| Monitoring
    Puma -->|"links to"| ZigUI

    %% Click Events
    click Puma "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/config/puma.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/controllers/madmin/devices_controller.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/controllers/madmin/mqtt_messages_controller.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/controllers/madmin/readings_controller.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/madmin/resources/device_resource.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/madmin/resources/mqtt_message_resource.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/madmin/resources/reading_resource.rb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/views/layouts/application.html.erb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/views/pwa/manifest.json.erb"
    click UI "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/views/pwa/service-worker.js"
    click JS "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/javascript/controllers/hello_controller.js"
    click JS "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/javascript/controllers/index.js"
    click Listener "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/config/initializers/mqtt_tasks.rb"
    click Listener "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/models/mqtt_message.rb"
    click DeviceModel "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/models/device.rb"
    click ReadingModel "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/app/models/reading.rb"
    click Schema "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/db/schema.rb"
    click Migration1 "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/db/migrate/20240804170449_create_mqtt_messages.rb"
    click Migration2 "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/db/migrate/20240807205258_create_devices.rb"
    click Migration3 "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/db/migrate/20240929104954_create_readings.rb"
    click AS "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/config/storage.yml"
    click AS "https://github.com/simoncoles/zigbee2mqtt-capture/tree/main/storage/"
    click Docker "https://github.com/simoncoles/zigbee2mqtt-capture/tree/main/Dockerfile"
    click DockerDev "https://github.com/simoncoles/zigbee2mqtt-capture/tree/main/ .devcontainer/Dockerfile"
    click Compose "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/ .devcontainer/compose.yaml"
    click Env "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/config/initializers/dotenv.rb"
    click Routes "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/config/routes.rb"
    click MadminRoutes "https://github.com/simoncoles/zigbee2mqtt-capture/blob/main/config/routes/madmin.rb"

    %% Styles
    classDef external fill:#ffebcd,stroke:#654321,color:#654321
    classDef appComp fill:#b3cde0,stroke:#03396c,color:#03396c
    classDef datastore fill:#ccebc5,stroke:#006400,color:#006400
    classDef storage fill:#decbe4,stroke:#800080,color:#800080
```
