React Integration – Visualization Layer for Device Models

KOS applications still use React for the UI layer, but React’s role changes fundamentally. Instead of React components managing complex state and business logic, they become pure visualization layers that display device state and provide user interaction points.

The React Role Shift

The Fundamental Shift: React as Display Layer

Traditional React Philosophy:
Components are smart – they fetch data, manage state, handle business logic, and render UI.

KOS React Philosophy:
Components are displays – they show device state and provide controls for device operations.

Traditional React: Components Do Everything

In traditional React applications, components are responsible for:

  • Data fetching: Making API calls and managing loading states
  • State management: Keeping track of application data and user interactions
  • Business logic: Implementing rules, validations, and workflows
  • Side effects: Managing timers, subscriptions, and cleanup
  • UI presentation: Rendering and user interaction handling

This creates heavy, complex components that are difficult to test and maintain.

KOS React: Components as Thin Display Layer

In KOS applications, React components become thin display layers:

  • Display device state: Show current temperature, door status, ingredient levels
  • Provide user controls: Buttons to start operations, adjust settings, view details
  • Handle pure UI state: Modal visibility, form inputs, animations
  • Route user actions: Pass clicks and inputs to model methods

The heavy lifting (device communication, state management, business logic) happens in the model layer.

Component Responsibility Examples

Traditional React Component:

  • Fetches sensor data every 5 seconds
  • Manages loading and error states
  • Validates sensor readings
  • Calculates average temperatures
  • Handles retry logic on failures
  • Renders the temperature display

KOS React Component:

  • Receives sensor data from model
  • Renders the temperature display
  • That’s it.

The model handles fetching, validation, calculations, errors, and state management.

The Connection: Models and Components

How Components Access Models

KOS provides a simple hook that connects React components to device models. This hook acts as a bridge between the model layer (which handles device logic) and the component layer (which handles presentation).

The Connection Process:

  1. Component requests access to a specific device model
  2. Framework provides live connection to that model’s current state
  3. When model state changes (from device events), component automatically re-renders
  4. When user interacts with component, component calls model methods

Automatic Synchronization

The beauty of this system is that synchronization is automatic:

  • Device changes → Model updates → Component re-renders → User sees change
  • User interaction → Component calls model → Model commands device → Device responds

No manual state management, no polling, no complex synchronization logic needed.

What Components Should Manage

React Components Should Handle:

  • Visual state: Is a modal open? Is an animation playing? Which tab is selected?
  • Form inputs: What did the user type in the text field?
  • UI feedback: Loading spinners, success messages, error displays
  • User preferences: Display settings, layout choices, view modes

React Components Should NOT Handle:

  • Device state: Current temperature, door status, ingredient levels
  • Device operations: Starting dispensing, adjusting temperature, calibrating sensors
  • Business logic: When to trigger alerts, how to validate operations
  • Real-time data: Sensor readings, operation progress, system status

Clear Boundary Examples

Good: UI State in React

  • “Show advanced controls panel” → React manages visibility
  • “User selected coffee size” → React tracks form selection until submitted
  • “Display temperature in Celsius” → React manages unit preference

Bad: Device State in React

  • “Current temperature is 72°F” → This comes from the device model
  • “Dispenser is currently pouring” → This is device operational state
  • “Low ingredient alert” → This is business logic from the model

Common Component Patterns

Display Components: Showing Device State

Purpose: Present current device information to users
Characteristics:

  • Read-only connection to models
  • Focus on visual presentation of data
  • No business logic, just formatting and display
  • Automatically update when device state changes

Examples:

  • Temperature readings with current values and timestamps
  • Door status indicators (open/closed/locked)
  • Ingredient level displays with visual gauges
  • System status dashboards with multiple metrics

Control Components: Device Operation Interface

Purpose: Provide user interface for device operations
Characteristics:

  • Trigger model operations through user interactions
  • Handle form inputs for operation parameters
  • Provide immediate feedback on user actions
  • Enable/disable controls based on device capabilities

Examples:

  • Beverage selection buttons for dispensers
  • Temperature adjustment controls for heating systems
  • Start/stop buttons for operations
  • Configuration forms for device settings

Status Components: Operation Feedback

Purpose: Show real-time operational state and progress
Characteristics:

  • Display ongoing operation status
  • Show progress indicators for long-running operations
  • Provide visual feedback for system health
  • Handle error states and recovery options

Examples:

  • Progress bars during dispensing operations
  • Status lights indicating system health
  • Alert panels for maintenance needs
  • Operation timers and completion estimates

Effects: Device vs UI Concerns

Traditional React: Effects Everywhere

In traditional React applications, components use effects for everything:

  • Data fetching when components mount
  • Subscriptions to external data sources
  • Timers and intervals for periodic updates
  • Business logic triggered by state changes
  • Cleanup when components unmount

This creates complex components with mixed concerns.

KOS Pattern: Effects by Domain

KOS separates effects by their domain of concern:

Device Effects (In Models):

  • Responding to device state changes
  • Triggering alerts when thresholds are exceeded
  • Coordinating multiple devices during operations
  • Managing device communication and recovery

UI Effects (In Components):

  • Managing animation timelines
  • Handling auto-hide timers for notifications
  • Focusing form inputs after state changes
  • Cleaning up UI subscriptions on unmount

The Boundary Rule

Device-Related Effects belong in models:

  • “When ingredient level drops below 10%, send supply alert”
  • “When temperature exceeds safe range, activate cooling”
  • “When door opens during operation, pause dispensing”

UI-Related Effects belong in components:

  • “When alert appears, auto-hide after 5 seconds”
  • “When form is submitted, focus on next input field”
  • “When modal opens, prevent body scrolling”

Form Handling: Device Configuration

Different Form Philosophy

Traditional Web Forms:

  • Form state represents data to be saved
  • Submit button saves form data to server
  • Form manages its own validation and error states
  • Optimistic updates assume save will succeed

KOS Device Configuration Forms:

  • Form state is temporary user input
  • Submit button sends configuration commands to device
  • Device reports back what settings were actually applied
  • No optimistic updates – wait for device confirmation

Configuration Flow

  1. Display Current Settings: Form shows device’s actual current configuration
  2. User Input: Form collects desired changes in temporary state
  3. Submit Configuration: Form sends configuration commands to device via model
  4. Device Response: Device applies what it can and reports back actual settings
  5. UI Update: Form displays the device’s confirmed settings, not the user’s input

This prevents the UI from showing configuration that doesn’t match the device’s actual state.

Error Handling: Source-Specific Responses

Error Domain Separation

Device Errors (Handled by Models):

  • Hardware communication failures
  • Device operational constraints
  • Safety interlock violations
  • Maintenance requirements

UI Errors (Handled by Components):

  • Form validation messages
  • Invalid user inputs
  • UI state inconsistencies
  • Display formatting issues

Component Error Responsibilities

React components handle presentation of errors, not error detection or recovery:

  • Display error messages provided by models
  • Provide retry buttons that call model recovery methods
  • Show error states with appropriate visual feedback
  • Guide users toward corrective actions

The Result: Simpler, Focused Components

Automatic Performance

The KOS model system handles performance automatically:

  • Smart re-rendering: Components only update when their connected model data actually changes
  • No manual optimization: No need for complex dependency arrays or memoization
  • Efficient updates: Only affected components re-render, not entire component trees

Reusable Components

When components focus purely on presentation, they become highly reusable:

  • Generic status displays that work with any model’s status property
  • Progress indicators that can show progress from any long-running operation
  • Alert components that display messages from any model’s error state
  • Control panels that can trigger operations on different device types

Easier Testing

Pure presentation components are much easier to test:

  • No mocking of complex APIs or async operations
  • Simple prop-based testing with mock model data
  • Visual regression testing focuses on actual UI behavior
  • Unit tests for presentation logic only, not business rules

The Mental Shift: React as Display Layer

From “React manages everything”

To “React displays device state”

This fundamental change affects every aspect of React development:

Traditional React Questions:

  • Where should this state live?
  • How do I fetch this data?
  • When should I trigger this effect?
  • How do I sync these components?

KOS React Questions:

  • What device state should this display?
  • How should I present this model’s data?
  • What user interactions trigger device operations?
  • How should I handle pure UI concerns?

The Benefit: Focused Development

Frontend developers can focus on what they do best:

  • Creating intuitive user interfaces
  • Handling accessibility and user experience
  • Managing visual state and interactions
  • Optimizing presentation performance

Device domain experts handle what they do best:

  • Device communication protocols
  • Business logic and operational constraints
  • Error handling and recovery
  • Real-time data processing

React becomes a visualization layer that translates device capabilities into great user experiences, without getting bogged down in device complexity.