Omnia: User Interface & Experience

Omnia provides the dashboard interface for the HALO ecosystem across tablets, wall displays, and mobile devices. The system consists of two distinct components: Omnia (Screen)—the React-based frontend application with dynamic widget loading—and Omnia (API)—the backend service running as a container on Nexus managing widget configurations, user profiles, and data persistence.

Built for modularity, Omnia transforms complex backend automation into intuitive visual interfaces that adapt to their context and purpose. The frontend deliberately avoids executing business logic, instead communicating with backend workflows through REST APIs and WebSocket connections proxied by Traefik. This separation ensures the UI remains responsive while automation logic stays centralized and maintainable in n8n workflows and backend services.

Purpose and Scope

Omnia’s mission is to centralize the home experience into a single intelligent interface that serves the needs of everyone in the household. It presents family-centric information like calendars, tasks, and reminders alongside real-time home status—lighting, temperature, security cameras, and device states. Through integration with Apollo, Omnia provides AI-assisted suggestions and context-aware recommendations that make the system feel intelligent rather than merely automated.

The system emphasizes modular extensibility through its widget architecture. Each feature in Omnia is delivered as a self-contained widget, housed in the packages/omnia-widgets/ directory and loaded dynamically at runtime through a manifest-driven loader. Widgets can display information (upcoming calendar events, sensor states, chat messages), accept input (adding tasks, scheduling appointments), or trigger automations through their associated workflows.

This widget-first architecture enables rapid feature development and customization without modifying the core Omnia application. New widgets can be developed independently, tested in isolation, and deployed by simply adding them to the widget registry.

Architecture and Design

Omnia is architected around clear separation of concerns, with each layer having a distinct responsibility:

Omnia (Screen) - React UI Layer: The single-page application served as static files through Traefik provides dynamic widget rendering with adaptive layouts that respond to screen size, orientation, and device capabilities. Widgets can be shown or hidden based on conditions like time of day, user profile, or device type.

Widget Loader: This system loads widget manifests from the packages directory and builds UI components at runtime. The loader handles widget lifecycle (mount, update, unmount), state management, and communication with backend services.

Omnia (API) - Backend Service: Running as a containerized service on Nexus, Omnia API handles authentication, configuration synchronization, widget state persistence, and user profiles. This API serves as the bridge between the UI and backend infrastructure, exposed through Traefik at /api/omnia.

Workflow Bridge: Defines the connection between UI widgets and backend n8n workflows or direct API calls. Widgets declare their workflow dependencies in their manifest, and the bridge handles invocation and response handling.

Local Storage: Retains layout preferences, widget configurations, and cached data for offline operation and fast initial load. This ensures the dashboard remains functional even during network interruptions.

Core Features and Capabilities

Family Dashboard

The central dashboard presents personal and shared event timelines, combining calendar events, reminders, tasks, and contextual information like weather and news. Multiple family members can have personalized views while sharing common information like grocery lists and household tasks.

Widget-Based Modularity

Each widget is completely self-contained, including its own configuration panel, visual UI component, and workflow bindings. Widgets can be conditionally displayed based on screen size (mobile vs tablet vs wall display), time of day (show morning routine widgets at sunrise), or user profile (admin vs guest vs child).

The widget manifest defines all aspects of the widget:

{
  "id": "weather-widget",
  "name": "Weather Forecast",
  "version": "1.0.0",
  "author": "HALO Team",
  "description": "Displays current weather and 5-day forecast",
  "component": "./WeatherWidget.jsx",
  "config": "./WeatherConfig.jsx",
  "workflows": {
    "updateWeather": "webhook-weather-update",
    "getLocation": "webhook-get-location"
  },
  "displays": ["tablet", "wall"],
  "defaultSize": { "width": 2, "height": 2 }
}

Secure Access

Omnia will use the Omnia API for authentication and role-based access control. Future enhancements include PIN locks, biometric authentication, and NFC-based screen unlocking for shared devices in common areas.

AI Assistant Integration

Widgets can send contextual prompts to Apollo and display returned insights directly in their interface. For example, a party planning widget might send the prompt “Plan a birthday party for next Saturday” to Apollo, which would then coordinate generating grocery lists, task assignments, music playlist suggestions, and lighting scene recommendations.

Smart Device Feedback

Through Home Assistant integration, Omnia displays real-time temperature, motion detection status, lighting states, and other sensor data. Control widgets provide buttons and sliders for adjusting devices, triggering scenes, and managing automation states. Voice control integration (planned) will allow hands-free operation through the same widget interfaces.

Security Monitoring

Frigate integration surfaces video feeds, detection events, and security alerts through dedicated widgets. The system can display annotated camera feeds with bounding boxes around detected objects, event timelines showing recent activity, and zone-specific monitoring for areas like the driveway or front door.

Extensibility and Development

Widget Development Model

Creating new Omnia widgets follows a straightforward pattern using the widget template repository. Widgets are developed in the packages/omnia-widgets/ directory with a structure like:

packages/omnia-widgets/
├── widgets/
│   ├── weather/
│   │   ├── manifest.json
│   │   ├── WeatherWidget.jsx
│   │   ├── WeatherConfig.jsx
│   │   └── styles.css
│   ├── calendar/
│   └── camera-feed/
└── shared/
    ├── components/
    ├── hooks/
    └── utils/

Each widget includes:

• Manifest File: Metadata, workflow mappings, display constraints
• Component File: React component implementing the widget UI
• Configuration File: Settings panel for user customization
• Optional Workflow: Default n8n workflow configuration

The shared directory provides pre-built components for common UI patterns (buttons, cards, grids, forms), hooks for workflow communication and state management, and utility functions for date formatting, data transformation, and API calls.

Backend Workflow Integration

Widgets connect to backend workflows rather than implementing logic directly. This pattern keeps the UI responsive while enabling complex multi-step operations that may involve multiple services.

For example, a calendar widget doesn’t directly manage calendar data—it calls an n8n workflow that handles the actual calendar service integration, validation, and storage. This approach allows:

• Service Abstraction: Switching calendar providers doesn’t require widget changes
• Complex Orchestration: Multi-service workflows (calendar + tasks + notifications)
• Error Handling: Centralized retry logic and failure handling
• Caching: Workflows can implement intelligent caching strategies

Widget-to-Widget Interaction

Widgets can cooperate through shared workflows or direct event communication. For instance:

1. Calendar Widget creates a party event
2. Event metadata flows to Chores Widget to generate cleanup tasks
3. Simultaneously updates Groceries Widget with party supply items
4. Calls Home Assistant to create a lighting scene for the party date

This coordination happens through:

• Workflow Routing: Shared triggers that fan out to multiple handlers
• Context Linking: Data passed between widget-configured workflows
• Event Bus: Direct widget-to-widget messages for UI updates

The Omnia widget loader manages these connections, ensuring widgets can discover and communicate with each other without tight coupling.

Directory Structure

Omnia is organized within the HALO monorepo:

halo/
├── apps/omnia-ui/              # React frontend application
│   ├── src/
│   │   ├── components/         # Core UI components
│   │   ├── layouts/            # Layout containers
│   │   ├── services/           # API clients
│   │   └── widgets/            # Widget loader and registry
│   └── public/
│       └── assets/             # Static resources
├── services/omnia-api/         # Backend API (planned)
│   └── src/
│       ├── api/                # REST endpoints
│       ├── auth/               # Authentication
│       └── db/                 # Database models
└── packages/omnia-widgets/     # Widget bundles
    ├── widgets/                # Individual widgets
    └── shared/                 # Shared components

This structure allows independent development of the UI, API, and widgets while maintaining cohesion through the monorepo.

Integration with Other HALO Systems

Nexus Integration

Omnia (Screen) is served as static files through the Traefik reverse proxy running on Nexus. Omnia (API) runs as a containerized service on Nexus, handling backend operations like widget configuration, user profiles, and data persistence. API calls from widgets flow through Traefik, which routes requests to appropriate backend services based on URL path and Docker service labels.

Apollo Integration

Apollo provides the AI reasoning layer for Omnia. Widgets can send prompts to Apollo via the /apollo API endpoint, receiving structured responses that might include text, suggested actions, or data for display. The chat widget serves as the primary Apollo interface, but any widget can leverage Apollo’s capabilities for context-aware assistance.

Home Assistant Integration

Omnia widgets make REST API calls to Home Assistant for device control and state queries. WebSocket connections provide real-time updates when device states change, ensuring the UI always reflects current home status. Widgets can trigger scenes, scripts, and automations through the Home Assistant service API.

Frigate Integration

Camera widgets display live feeds from Frigate using its REST API endpoints. Event widgets subscribe to Frigate’s MQTT topics for real-time detection notifications. The system can show annotated feeds with bounding boxes around detected objects and provide playback of recorded events.

Deployment and Development

Running Omnia

Omnia (Screen) and Omnia (API) are deployed through Nexus infrastructure:

# Build production bundle for Omnia (Screen)
cd apps/omnia-ui
npm run build

# Deploy to Traefik static file volume
# Served at https://halo.local/

# Deploy Omnia (API) container
cd nexus
.\scripts\deploy.ps1 -Files @("compose\omnia-api.yml")
# API available at https://halo.local/api/omnia

Development Workflow

# Start development server
cd apps/omnia-ui
npm run dev

# Develop widgets in isolation
cd packages/omnia-widgets
npm run widget:dev -- --widget=weather

The development server provides hot module reloading for rapid iteration. Widgets can be tested in isolation before deployment to the full dashboard.

Security Considerations

Omnia implements security at multiple levels:

Network Isolation: UI served only through Traefik reverse proxy with TLS termination

API Authentication: All backend API calls to Omnia (API) require authentication tokens

Role-Based Access: Different user profiles have different widget visibility and control permissions

Local-First Data: Sensitive information cached locally, never sent to external services without explicit user consent

Content Security: Strict CSP headers prevent XSS attacks and unauthorized script execution

Future enhancements include OAuth2 integration, biometric authentication for mobile apps, and hardware-based device authentication for wall displays.

Roadmap and Future Development

The Omnia roadmap includes several planned enhancements:

Visual Layout Editor: Drag-and-drop interface for arranging widgets, resizing panels, and creating custom layouts per device and user profile

Global Action Overlay: A universal “New” button that allows quick creation of events, notes, tasks, or reminders from anywhere in the interface

Workflow Monitor: Live status dashboard showing execution state of connected workflows with success/failure indicators and retry controls

Native Mobile Apps: iOS and Android applications using React Native or Capacitor to provide native OS integration and offline capabilities

Widget Marketplace: Community-contributed widgets with ratings, version management, and automatic updates

Multi-User Sync: Real-time synchronization of widget states across devices when multiple family members interact simultaneously

Developer Resources

The Omnia Widget Template provides a starting point for custom widget development:

• Repository: dcampman/omnia-widget-template
• Documentation: Widget development guide in docs/guides/
• Examples: Sample widgets in packages/omnia-widgets/widgets/

Pre-built shared components provide consistent UI patterns:

• Layout components (Grid, Card, Panel)
• Input components (Button, TextField, Toggle, Slider)
• Data display (Chart, Table, Timeline)
• Theme integration (colors, typography, spacing)

Related Documentation

For widget development patterns, see Widget Documentation.

For core architecture details, see Omnia Core.

For backend integration patterns, see Nexus Overview and n8n Workflows.