Skip to content

Architecture

Overview

JunctionRelay is a fully modular, zero-trust, open-source IoT orchestration platform designed to securely manage local and cloud-connected devices. Its architecture cleanly separates frontend, backend, device, and cloud responsibilities to maximize security, reliability, and scalability.

The platform operates in fully offline, fully cloud-connected, or hybrid modes while maintaining strict zero-trust guarantees throughout all components.

High-Level Architecture Diagram

    +-------------------------+           +--------------------------+          +-------------------------+
    |  JunctionRelay_Server_  |  API ->   | JunctionRelay_Cloud      |  API ->  |  Stripe + Clerk Cloud   |
    |  Frontend (React SPA)   |           | Backend (Cloud BFF)      |          |  SaaS Providers         |
    +-------------------------+           +--------------------------+          +-------------------------+
            |                                      |
            | REST API (Zero Trust Proxy)         | Redis Streams (task queue)
            |                                      |
    +-------------------------+           +--------------------------+
    |  JunctionRelay_Server_  |  <--> DB  | JunctionRelay_Worker     |
    |  Local Backend (.NET 8) |  <--> Redis Stream  | (Cloud worker) |
    +-------------------------+           +--------------------------+
            |
    +-------------------------+
    |  ESP32 Devices (LVGL)   |
    +-------------------------+

Core Components

1️⃣ JunctionRelay_Server_Local (Zero Trust Backend)

  • Deployment: Fully self-hostable Docker container or native .NET 8 service
  • Database: Embedded SQLite for fully local data storage
  • Auth Modes: none, local, or cloud via proxy Clerk OAuth
  • API-first Design: Full REST API surface for all device, collector, junction, and payload orchestration
  • LAN Device WebSocket Gateway: Real-time device streaming via native WebSocket interface
  • Collectors: Poll external platforms (HomeAssistant, LibreHardwareMonitor, MQTT, HTTP)
  • Payload Processing: Generate LVGL JSON screen layouts per device and junction configuration
  • Broker Output Streaming: Send calculated payloads via MQTT, HTTP, or Serial COM output brokers

2️⃣ JunctionRelay_Server_Frontend (Zero Trust Frontend)

  • Type: Fully static React SPA (TypeScript, Material-UI)
  • Deployment: Render Static Site, any CDN, or local file server
  • Zero Trust Guarantee: No secrets or credentials embedded; strictly API-driven
  • Main Workflows:
  • Device onboarding, preferences, firmware, sensors, screens
  • Collector integration and mapping
  • Junction orchestration with full source-target linking
  • LVGL payload preview with live sensor simulation
  • OTA firmware manager
  • Cloud proxy device approvals
  • Host system telemetry dashboards
  • Complete global settings and feature flags management

3️⃣ JunctionRelay_Cloud (Cloud Backend BFF)

  • Type: Secure cloud backend
  • Deployment: Render Web Service (Docker)
  • Responsibilities:
  • Proxy Clerk OAuth flows
  • Issue backend JWT tokens
  • Enforce Stripe billing and licensing enforcement
  • Proxy all device registration flows securely
  • Device refresh token management
  • Fully state-isolated Zero Trust model (cloud never directly connects to local instance)

4️⃣ JunctionRelay_Worker (Cloud Background Worker)

  • Type: Stateless cloud background worker
  • Deployment: Render Background Worker (Docker)
  • Responsibilities:
  • Consume Redis Streams from cloud backend
  • Perform safe atomic inserts into Postgres
  • Manage device registration confirmations and DB writes
  • Isolate potentially blocking workloads from cloud backend API

5️⃣ JunctionRelay_Dashboard (Cloud Web UI)

  • Type: React SPA (standalone from local frontend)
  • Deployment: Render Static Site (or any CDN)
  • Responsibilities:
  • Cloud-only license holders portal
  • Cloud device registration management and approvals
  • Cloud billing portal entry points via Stripe
  • Securely operates entirely via cloud backend API

6️⃣ ESP32 Devices (LVGL Display Clients)

  • Firmware Stack: Lightweight Arduino-based JunctionRelay SDK
  • Registration Flow:
  • Secure device registration token flow via cloud backend
  • Hardware MAC-based unique device identification
  • Persistent local storage of issued JWT tokens (Preferences API)
  • Health Reporting:
  • Automatic periodic health reports (uptime, heap, RSSI, sensors)
  • Custom sensor injection with each report cycle
  • Fully client-side resilience and retry handling

Data Flow Summary

Local Device → Local Backend (Direct WebSocket)

  • Devices communicate directly over LAN to WebSocket gateway

Device → Cloud Backend (Proxy HTTPS)

  • Devices can optionally register via secure cloud API for cloud license holders
  • Registration tokens enforce short-lived secure device onboarding

Cloud Backend → Redis Stream

  • Cloud backend pushes device registration events to Redis streams for worker processing

Cloud Worker → Postgres

  • Worker processes Redis tasks asynchronously and atomically updates DB state

Frontend → Local Backend API

  • All management UIs communicate exclusively with secured local backend APIs

Frontend → Cloud Backend Proxy API

  • Cloud Proxy functions only available when licensed; strictly proxy via local backend

Security Model

  • Full Zero Trust architecture across all components
  • Cloud credentials never exposed to local backend or frontend
  • OAuth code exchange entirely backend-proxied
  • Local admin authentication fully offline capable
  • Clerk OAuth tokens exchanged server-side only
  • Device credentials never reach frontend UI layer
  • API token lifetimes are short-lived and ephemeral
  • Strict separation of public vs trusted services
  • Redis stream isolation for queuing sensitive device onboarding
  • OTA firmware distribution validated server-side before any flashing

Deployment Model Summary

Component Deployment Hosting
JunctionRelay_Server_Local Docker Container Self-hosted LAN server
JunctionRelay_Server_Frontend Static Site Any CDN / Render Static
JunctionRelay_Cloud Web Service Render Cloud Backend
JunctionRelay_Worker Background Worker Render Worker Instance
JunctionRelay_Dashboard Static Site Render Cloud Dashboard
ESP32 Devices Embedded Firmware Local WiFi / Ethernet

Key Design Principles

  • ✅ Zero Trust at every boundary
  • ✅ Full hybrid offline/cloud operational model
  • ✅ Strict API-first contract across all components
  • ✅ No privileged cloud access to local environments
  • ✅ Open-source self-hosted by design
  • ✅ Fully containerized, portable deployment options
  • ✅ Modular scalability (each service scales independently)
  • ✅ Support for both Pro cloud licensing and 100% offline OSS usage