How simoncoles/zigbee2mqtt-capture works
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”.