System Architecture

Learn how Homix's cloud-first, NATS-based architecture works.

Overview

Homix uses a distributed architecture that combines edge computing with cloud management. The system is built around NATS messaging for real-time communication between components.

Core Components

Edge Server

The edge server runs locally in your home and serves as the bridge between your devices and the cloud. It handles:

• Device Communication: Direct integration with smart home devices
• Local Automation: Execute automations without cloud dependency
• State Management: Cache device states locally
• Protocol Translation: Convert between device protocols and NATS
• Cloud Synchronization: Keep cloud in sync with local state

NATS Messaging

NATS provides the messaging backbone for Homix, enabling:

• Real-Time Communication: Instant message delivery
• Publish-Subscribe: Decoupled component communication
• Persistent Streams: JetStream for reliable message delivery
• Key-Value Store: Distributed state management
• Request-Reply: Synchronous operations when needed

Cloud Dashboard

The web-based dashboard connects directly to NATS via WebSocket, providing:

• Real-Time Updates: Live device state changes
• Visual Automation Designer: Drag-and-drop automation creation
• Remote Management: Control devices from anywhere
• Multi-Home Support: Manage multiple edge servers

NATS Subject Structure

Homix uses a hierarchical subject structure for organizing messages:

Data Flow

Device State Updates

1. Device changes state (e.g., light turns on)
2. Edge server detects change
3. Edge server publishes to home.devices.light1.state
4. Cloud dashboard receives update via NATS WebSocket
5. UI updates in real-time

Device Commands

1. User clicks button in dashboard
2. Dashboard publishes to home.devices.light1.command
3. Edge server receives command
4. Edge server executes command on device
5. Device state update flows back (see above)

Automation Execution

1. Trigger condition met (e.g., time of day)
2. Edge server publishes trigger event
3. Automation engine processes trigger
4. Actions executed (device commands, notifications, etc.)
5. Status updates published to cloud

Key-Value Storage

Homix uses NATS KV buckets for distributed state management:

Security

Authentication

Homix uses NATS JWT authentication via Synadia Cloud:

• Credentials Files: Securely store authentication tokens
• Automatic Rotation: Tokens refreshed automatically
• Scoped Access: Fine-grained permissions per component

Transport Security

• TLS Encryption: All NATS traffic encrypted in transit
• WebSocket Security: WSS for browser connections
• Certificate Validation: Verify server identity

Scalability

Horizontal Scaling

The architecture supports scaling in multiple dimensions:

• Multiple Homes: Each edge server operates independently
• Device Scaling: Support for thousands of devices per home
• Geographic Distribution: Global NATS infrastructure
• Load Balancing: Multiple cloud dashboard instances

Performance Characteristics

• Low Latency: Sub-second response times
• High Throughput: Thousands of messages per second
• Efficient Bandwidth: Binary protocol with compression
• Local Processing: Reduced cloud dependency

Deployment Patterns

Single Home

Basic deployment with one edge server and cloud access:

• Edge server in home network
• Synadia Cloud for messaging
• Web dashboard for management

Multi-Home

Multiple properties with centralized management:

• Edge server per location
• Shared cloud dashboard
• Cross-home automations possible

Air-Gapped

Local-only deployment without cloud connectivity:

• Edge server with local NATS
• Local dashboard only
• No remote access

Design Principles

Cloud-First

Designed for cloud management with local execution for reliability.

Event-Driven

All communication happens through events, enabling loose coupling and scalability.

Real-Time

Low-latency messaging ensures immediate response to device changes and user actions.

Fault Tolerant

System continues operating during network partitions and component failures.

Next Steps

To learn more about specific components: