Separation of Concerns in KOS – Clean Boundaries for Device Applications

KOS applications achieve clean separation of concerns by establishing clear boundaries between device logic, business logic, and presentation logic. This separation makes applications more maintainable, testable, and reliable.

The Three-Layer Architecture

Traditional Web App Layers

Traditional web applications often have blurred boundaries:

Mixed Concerns Problems:
Traditional React components often handle everything:

  • Data fetching (API calls to get products)
  • Business logic (stock validation, cart limits)
  • State management (keeping track of products and cart)
  • UI presentation (rendering lists and buttons)
  • Error handling (showing success/error messages)

This creates complex, hard-to-test components where changes to business rules require touching UI code, and UI changes can accidentally break business logic.

KOS Clear Separation

KOS applications maintain distinct layers with specific responsibilities and clear ownership:

Model Layer (Standalone TypeScript – Independent Domain):

  • Device communication and state management
  • Hardware constraints and capabilities
  • Event handling and device protocols
  • Business logic and operational rules
  • Independent of any UI framework
  • Created by developers who understand device domain

Presentation Layer (React – UI Domain):

  • User interface and interaction
  • Visual feedback and animations
  • Pure UI state management
  • Consumes models through hooks
  • Created by developers focused on user experience

Developer Expertise Requirements

Model Layer Responsibilities:

  • Understanding device communication services
  • Knowledge of hardware protocols and limitations
  • Familiarity with operational constraints and safety requirements
  • Can be written by any developer with device domain knowledge

Presentation Layer Responsibilities:

  • Understanding user experience and accessibility
  • Knowledge of visual design and interaction patterns
  • Skills in responsive layouts and animations
  • Can be written by any developer with UI/UX focus

Device Logic Boundaries

What Belongs in Device Logic

Device Communication:

  • WebSocket topic subscriptions
  • Device command protocols
  • State synchronization patterns
  • Error handling for hardware failures

Device Constraints:

  • Physical limitations (temperature ranges, flow rates)
  • Operational modes (heating, cooling, idle)
  • Safety interlocks and validations
  • Hardware-specific timing requirements

Device Logic Responsibilities:

What BELONGS in Device Logic:

  • Device communication: Receiving sensor readings, sending commands
  • Hardware constraints: Valid temperature ranges, operational limits
  • Device-specific validation: Is this reading within sensor capabilities?
  • Device operations: Calibration, status checking, error detection
  • Physical safety: Preventing unsafe device states

What DOESN’T BELONG in Device Logic:

UI Concerns:

  • Display preferences (Celsius vs Fahrenheit)
  • Whether control panels are expanded or collapsed
  • Animation states and transitions
  • Form input validation messages

Application-Level Business Logic:

  • User alert preferences and thresholds
  • Permission checking and access control
  • Cross-system workflows and coordination
  • Reporting and data aggregation rules

Business Logic Boundaries

What Belongs in Business Logic

Application Rules:

  • When to trigger alerts or notifications
  • How to coordinate multiple devices
  • User permissions and access control
  • Data aggregation and reporting

Cross-Device Coordination:

  • System-wide operational modes
  • Device orchestration workflows
  • Resource allocation and scheduling
  • Performance optimization strategies

Business Logic Responsibilities:

What BELONGS in Business Logic:

  • System coordination: When multiple devices need to work together
  • Application rules: Temperature thresholds, operational schedules
  • User permissions: Who can adjust settings, start operations
  • Cross-device workflows: Startup sequences, maintenance coordination
  • Data aggregation: Combining information from multiple sources

What DOESN’T BELONG in Business Logic:

Low-Level Device Details:

  • Specific communication protocols (WebSocket topics, message formats)
  • Hardware error codes and diagnostic information
  • Device-specific timing and operational sequences
  • Physical sensor calibration and validation

UI Presentation Concerns:

  • Which tab is currently selected
  • Whether modals are open or closed
  • Form validation error messages
  • Display formatting and layout preferences

Presentation Logic Boundaries

What Belongs in Presentation Logic

Visual State:

  • Modal open/closed states
  • Animation and transition states
  • Form input validation messages
  • Loading and progress indicators

User Interaction:

  • Click handlers and form submissions
  • Keyboard navigation and accessibility
  • Drag and drop interactions
  • Touch gestures and responsive behavior

Presentation Logic Responsibilities:

What BELONGS in Presentation Logic:

  • Visual state management: Which tab is active, is modal open, animation states
  • User interaction handling: Click events, form submissions, drag and drop
  • Display formatting: Color coding, unit conversions, layout calculations
  • Accessibility features: Keyboard navigation, screen reader support
  • Responsive behavior: Mobile layouts, touch gestures, viewport adjustments

What DOESN’T BELONG in Presentation Logic:

Device Communication:

  • Direct WebSocket connections to devices
  • Parsing device-specific message formats
  • Handling device connection states and retries
  • Managing device authentication and security

Business Logic:

  • Permission checking and user authorization
  • Operational rules and thresholds
  • Cross-system coordination logic
  • Data validation beyond basic UI formatting

Communication Between Layers

The Flow of Information and Control

Information Flows Down (Device State → UI):

Device State → Model Layer → Presentation Layer
  • Temperature sensor reports 72°F → Model updates → UI shows “72°F”
  • Door sensor reports “open” → Model updates → UI shows door icon as open
  • Operation completes → Model updates → UI shows success message

Commands Flow Up (User Actions → Device):

User Interaction → Presentation Layer → Model Layer → Device Command
  • User clicks “Start Heating” → UI component → Business model → Device model → Hardware command
  • User adjusts temperature → Form input → Business validation → Device temperature command

Layer Responsibility in Communication

Presentation Layer:

  • Translates user interactions into model method calls
  • Displays model state changes in user-friendly formats
  • Handles UI-specific error presentation and feedback

Model Layer:

  • Validates business rules before sending device commands
  • Coordinates multiple devices for complex operations
  • Translates device events into application state changes

Device Layer:

  • Communicates directly with physical hardware
  • Reports device state changes via events
  • Validates device-specific constraints and safety limits

Testing Benefits of Clean Separation

Focused, Isolated Testing

Device Layer Testing:

  • Focus: Test device communication, constraint validation, safety checks
  • Isolation: Mock device responses, no UI or business logic involved
  • Clarity: Test actual device behavior patterns and error conditions

Business Layer Testing:

  • Focus: Test coordination logic, business rules, user permissions
  • Isolation: Mock device models, no UI or hardware dependencies
  • Clarity: Test business scenarios and workflow logic

Presentation Layer Testing:

  • Focus: Test visual behavior, user interactions, accessibility
  • Isolation: Mock model data, no device or business complexity
  • Clarity: Test UI behavior and user experience patterns

Testing Advantages

Simpler Test Setup:
Each layer can be tested with simple, focused mocks rather than complex integration scenarios.

Faster Test Execution:
No need for full system integration when testing individual layer logic.

Clearer Test Failures:
When tests fail, the failure is clearly in device logic, business logic, or presentation logic.

Better Coverage:
Each concern can be thoroughly tested without interference from other layers.

Benefits of Clean Separation

1. Maintainability

  • Changes to device protocols only affect device models
  • UI improvements don’t require business logic changes
  • Business rule changes are isolated from device and UI code

2. Testability

  • Each layer can be tested independently
  • Mock interfaces are clear and simple
  • Integration testing is focused and reliable

3. Reusability

  • Device models can be reused across applications
  • UI components can work with different business models
  • Business logic can support multiple device types

4. Scalability

  • New devices only require new device models
  • New business rules don’t affect existing device code
  • UI improvements don’t impact device performance

The Mental Framework

Ask for Each Piece of Code:

“Is this about device capabilities?”
→ Device Model

“Is this about business rules or coordination?”
→ Business Model

“Is this about user interface or presentation?”
→ React Component

Red Flags for Boundary Violations:

  • Device communication in UI components
  • UI state in device models
  • Business rules mixed with device protocols
  • Presentation logic in business models

Clean separation of concerns makes KOS applications predictable, maintainable, and reliable by ensuring each part of the system has a clear, focused responsibility.