MOBIUS.TILES — Engineering Systems Architecture

Document Version 5.0.0 — Auth, KPI Analytics, Camera/NVR, Multi-Hub v2 — April 2026
Supersedes v4.0.0 (March 2026) — Multi-Hub Native Routing, PreferenceManager, DataCacheManager

1. System Overview

MOBIUS.TILES is a self-hosted smart-home control interface for Hubitat Elevation hubs. It provides a real-time tile dashboard for controlling lights, switches, dimmers, thermostats, locks, sensors, and cameras — with multi-hub support, per-user preferences, session-based authentication, historical KPI analytics, and WebRTC camera streams from a MediaMTX NVR.

Primary Capabilities

• Device Control: Lights, dimmers, switches, locks, thermostats, buttons via Hubitat Maker API
• Real-Time State: Instant UI updates from Hubitat webhooks via Server-Sent Events
• Multi-Hub: Devices aggregated from multiple Hubitat hubs; commands routed to originating hub
• KPI Dashboard: Environment section with 7 analytics cards — historic daily-avg charts, power fleet, status grids
• Camera Streams: WebRTC (WHEP) streams from MediaMTX NVR with MJPEG fallback
• Authentication: Session-based login, per-user preferences, admin user management
• Preferences: Three-layer persistence: in-memory → localStorage → PostgreSQL
• Fibonacci Grid: Auto-sectioning of devices by capability with responsive Fibonacci tile layout

2. Technology Stack

3. Architecture Overview

4. Module Architecture

Module Responsibilities

5. Device Classification System

Devices arriving from the Hubitat Maker API carry a type field and a capabilities array. DeviceFactory uses a priority-ordered detection chain to produce the correct subclass instance.

Type Detection Priority

Device Class Hierarchy

6. State Management

DeviceStateManager is the single source of truth for runtime device attribute state. It decouples the WebSocket event pipeline from the UI rendering layer.

Subscription API

// Register a listener for a specific device
const unsub = stateManager.subscribe(deviceId, (newState) => {
    // newState: string or object depending on attribute type
    device.updateAttribute(attrName, newState);
    device.updateUI();
});

// Unsubscribe on cleanup
unsub();

7. Real-Time Communication

SSE / Webhook Pipeline

Hubitat pushes device state changes to POST /api/webhook/event. Flask enqueues the event and fans it out to all connected browser tabs via a Server-Sent Events stream at GET /api/events/stream.

# Hubitat webhook payload example
{
  "deviceId": "42",
  "name": "switch",
  "value": "on",
  "displayName": "Living Room Lamp"
}

WebRTC Camera Streams

Camera tiles use WHEP (WebRTC-HTTP Egress Protocol) to stream directly from MediaMTX. The browser negotiates an RTCPeerConnection via HTTP offer/answer exchange with the NVR's WHEP endpoint — no Flask proxy involved in the media path.

// WHEP stream setup (simplified)
const pc = new RTCPeerConnection();
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const resp = await fetch(whepEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/sdp' },
    body: offer.sdp
});
const answer = await resp.text();
await pc.setRemoteDescription({ type: 'answer', sdp: answer });
// ICE candidates added → stream plays in <video>

Reconnection Strategy

8. API Reference

Device Operations

Hub Configuration

User Preferences

NVR / Camera

KPI Analytics

Authentication

System

9. UI Architecture

Section Structure

The UI is organized into named sections. The landing page shows section tiles; clicking a tile navigates to that section's device grid.

Fibonacci Grid Layout

Device tiles within a section are arranged using a Fibonacci sequence (1, 1, 2, 3, 5…) column count that adapts to container width. DeviceSectionizer calculates the optimal column distribution based on device count and screen size, creating a visually balanced non-uniform grid.

10. KPI Analytics System

The Environment section renders the SensorKpiDashboard — a self-contained analytics module with 7 cards. No external chart libraries; pure SVG + DOM.

Card Types

Data Flow

Deduplication

LAN devices configured natively on multiple Hubitat hubs appear in multiple device pools with identical labels. _dedupeByLabel(devices) keeps only the first occurrence per normalized label, applied to: continuous metrics, motion, contact, presence, and battery pools.

Modal Interaction

Double-click any KPI card → KpiModal overlay (full viewport, no backdrop close, × button). Two tabs:

• Overview: Larger version of the card visualization (90-day history for historic cards, full device list with names for fleet/grid cards).
• Settings: Per-card configuration — outdoor device selection, main power device radio, fleet ignore list. Preferences saved via preferenceManager.set('kpi', key, value).

Preference Keys (namespace: 'kpi')

11. Camera & NVR Integration

Camera tiles stream live video from a MediaMTX NVR instance using WHEP (WebRTC-HTTP Egress Protocol). The media path is entirely browser ↔ NVR — Flask only proxies the camera list and snapshot endpoints.

Stream Architecture

Lifecycle

1. UIManager calls CameraStreamManager.init(nvrBaseUrl) on app start
2. When the camera section becomes visible, CameraStreamManager.start(deviceId, nvrCameraId, videoEl) creates a MediaMTXWebRTCReader
3. Reader negotiates WHEP: POST SDP offer → receive SDP answer → set remote description → ICE candidates → stream plays
4. When section hides: CameraStreamManager.pauseAll() — closes RTCPeerConnection to save bandwidth
5. On section show: streams restart from step 2
6. MJPEG fallback activates if WebRTC fails after 3 retries or on unsupported browser

12. Authentication & User Management

Session-based authentication with bcrypt password hashing. All API routes (except /health, /api/auth/login) are protected by the @login_required decorator.

Auth Flow

Trusted Network Auto-Login

When enabled by admin in Security settings: clients on the same /24 subnet as the TILES host are automatically authenticated as the admin user without a login prompt. Checked on every request; subnet comparison uses ipaddress module. Result cached for 30 seconds.

Row-Level Security

PostgreSQL RLS is enabled on all user-data tables. Users can only read/write their own rows. Admin role bypasses RLS for user management operations.

13. Multi-Hub Native Routing

TILES supports a main Hubitat hub plus N additional hubs. All device pools are merged at /api/devices/native; each device is tagged with its origin hubIp and hubName. Commands are routed directly to the device's hub.

Device Discovery Flow

Command Routing

# Flask: POST /api/device/{id}/command
# Device carries its origin hubIp → route command there
target_url = f"http://{device.hubIp}/apps/api/{app_id}/devices/{device_id}/{command}"

Hub Link (Blue Dot)

Each device tile shows a small blue dot linking to the device's page on its originating Hubitat hub. Link uses device.hubIp — not the main hub's IP — ensuring the link is always correct for devices from additional hubs.

14. PreferenceManager & Settings Propagation

PreferenceManager provides a namespace-keyed preference API with three-layer persistence:

// Read (sync, from memory cache)
const unit = preferenceManager.get('sensors', 'tempUnit', 'F');

// Write (sync to memory+localStorage, async to DB)
preferenceManager.set('kpi', 'mainPowerDeviceId', deviceId);

Preference Categories

15. DataCacheManager & Device Polling

DataCacheManager caches the device list in localStorage and polls /api/devices/native in the background. A structural diff compares the new device list against the cached version — only triggers a UI re-render when devices are added, removed, or their type changes. Attribute-only changes flow through the WebSocket pipeline instead.

// Cache registration
cacheManager.register({
    key: 'devices',
    endpoint: '/api/devices/native',
    ttl: 300_000,  // 5 min
    onChange: (devices) => uiManager.renderDevices(devices)
});

16. Database Schema

Authentication & Sessions

users (
    id              SERIAL PRIMARY KEY,
    username        VARCHAR(64) UNIQUE NOT NULL,
    password_hash   VARCHAR(255) NOT NULL,   -- bcrypt
    role            VARCHAR(16) DEFAULT 'user', -- 'admin' | 'user'
    active          BOOLEAN DEFAULT TRUE,
    auth_enabled    BOOLEAN DEFAULT TRUE,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    updated_at      TIMESTAMPTZ
)

sessions (
    id              BIGSERIAL PRIMARY KEY,
    user_id         INTEGER REFERENCES users(id) ON DELETE CASCADE,
    session_token   UUID UNIQUE NOT NULL,
    ip_address      VARCHAR(45),
    user_agent      TEXT,
    expires_at      TIMESTAMPTZ NOT NULL,
    timeout_minutes INTEGER DEFAULT 1440,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    last_activity   TIMESTAMPTZ DEFAULT NOW()
)
-- Indexes: session_token, user_id, expires_at

User Preferences

user_preferences (
    id                BIGSERIAL PRIMARY KEY,
    user_id           INTEGER REFERENCES users(id) ON DELETE CASCADE,
    category          VARCHAR(64) NOT NULL,   -- 'kpi', 'sensors', 'appearance', …
    preference_key    VARCHAR(128) NOT NULL,
    preference_value  JSONB NOT NULL,
    updated_at        TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE (user_id, category, preference_key)
)

user_settings (
    id             BIGSERIAL PRIMARY KEY,
    user_id        INTEGER REFERENCES users(id) ON DELETE CASCADE,
    setting_key    VARCHAR(128) NOT NULL,
    setting_value  JSONB,
    updated_at     TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE (user_id, setting_key)
)

Hub Configuration

hub_configurations (
    id            SERIAL PRIMARY KEY,
    user_id       INTEGER REFERENCES users(id) ON DELETE CASCADE,
    hub_type      VARCHAR(16) NOT NULL,   -- 'main' | 'additional'
    hub_ip        VARCHAR(64) NOT NULL,
    app_number    VARCHAR(16),
    access_token  VARCHAR(255),
    hub_name      VARCHAR(128),
    hub_order     INTEGER DEFAULT 0,
    active        BOOLEAN DEFAULT TRUE,
    created_at    TIMESTAMPTZ DEFAULT NOW(),
    updated_at    TIMESTAMPTZ,
    UNIQUE (user_id, hub_type) WHERE hub_type = 'main'
)

KPI Analytics

kpi_sensor_readings (
    id         BIGSERIAL PRIMARY KEY,
    device_id  VARCHAR(128) NOT NULL,
    label      VARCHAR(255),
    metric     VARCHAR(32) NOT NULL,   -- 'temperature', 'power', 'outdoorTemperature'
    value      DOUBLE PRECISION NOT NULL,
    ts         BIGINT NOT NULL         -- Unix ms timestamp
)
-- Index: (metric, ts) for daily-average range queries
-- Populated by POST /api/kpi/readings every 30 seconds from the frontend

Device Metadata

device_selections (
    id                   SERIAL PRIMARY KEY,
    user_id              INTEGER REFERENCES users(id),
    selection_type       VARCHAR(64),   -- 'preferred_lock', 'temperature_sensor', …
    device_id            VARCHAR(64),
    linked_device_id     VARCHAR(64),
    selection_metadata   JSONB,
    UNIQUE (user_id, selection_type, device_id)
)

device_matter_map (
    id                   SERIAL PRIMARY KEY,
    hubitat_device_id    VARCHAR(64) UNIQUE NOT NULL,
    hubitat_device_label VARCHAR(255),
    matter_node_id       VARCHAR(64),
    matter_endpoint_id   VARCHAR(32),
    device_type          VARCHAR(64),
    active               BOOLEAN DEFAULT TRUE
)

17. Deployment Architecture

Docker Services

Volume Mounts

Environment Variables

Gunicorn Configuration

# gunicorn.conf.py (key settings for SSE)
worker_class = "gthread"
workers = 2
threads = 8
timeout = 120
keepalive = 5
# SSE requires long-lived connections — sync workers would block

Startup Sequence