Skip to content

Architecture Overview

This document provides a detailed overview of the Unraid integration's architecture, explaining how the various components work together.

High-Level Architecture

The Unraid integration follows a layered architecture pattern:

[Diagram: High-level architecture showing the layered components of the Unraid integration, including Home Assistant layer, API layer, and Unraid server layer]

Note: A detailed architecture diagram will be added in a future update.

Key Components

Home Assistant Integration Layer

This is the top layer that integrates with Home Assistant's framework:

  1. Config Flow (config_flow.py):
  2. Handles setup and configuration of the integration
  3. Validates connection settings

  4. Manages integration options

  5. Data Update Coordinator (coordinator.py):

  6. Central component managing all data updates
  7. Implements intelligent update scheduling
  8. Provides data to all entities

  9. Manages caching and state preservation

  10. Entity Platforms:

  11. Sensors (sensor.py, sensors/): Read-only data points
  12. Binary Sensors (binary_sensor.py, diagnostics/): Boolean state sensors
  13. Switches (switch.py): Toggleable controls

  14. Buttons (button.py): Action triggers

  15. Services (services.py):

  16. Provides Home Assistant services for performing actions
  17. Handles command execution and parameter validation

API Layer

The middle layer that handles communication with the Unraid server:

  1. API Client (unraid.py):
  2. Main client class combining functionality from mixins

  3. Provides consistent interface for all operations

  4. Connection Manager (api/connection_manager.py):

  5. Manages SSH connections with connection pooling
  6. Implements circuit breaking and retry logic

  7. Provides fault tolerance and health monitoring

  8. Cache Manager (api/cache_manager.py):

  9. Optimizes performance by caching data
  10. Implements TTL-based cache invalidation

  11. Prioritizes data based on importance

  12. API Modules:

  13. System Operations (api/system_operations.py): System information
  14. Disk Operations (api/disk_operations.py): Array and disk management
  15. Docker Operations (api/docker_operations.py): Container control
  16. VM Operations (api/vm_operations.py): Virtual machine management
  17. UPS Operations (api/ups_operations.py): UPS monitoring
  18. User Script Operations (api/userscript_operations.py): User script execution
  19. Network Operations (api/network_operations.py): Network statistics

Unraid Layer

The actual Unraid server that the integration communicates with:

  1. SSH Connection:
  2. Primary communication channel

  3. Used for executing commands and retrieving data

  4. Unraid Components:

  5. System: OS and hardware information
  6. Docker: Container management system
  7. VMs: Virtual machines
  8. Array & Disks: Storage system
  9. UPS: Uninterruptible power supply
  10. User Scripts: Custom scripts defined in Unraid

Data Flow

  1. Configuration and Initialization:
  2. User configures the integration through the UI
  3. Home Assistant creates a ConfigEntry
  4. Integration sets up the coordinator and API client

  5. Platforms register entities with Home Assistant

  6. Data Update Cycle:

  7. Coordinator schedules regular updates
  8. API client requests data from the Unraid server
  9. Data is processed, normalized, and cached

  10. Entities receive updated data through the coordinator

  11. User Actions:

  12. User interacts with an entity (e.g., switch, button)
  13. Entity calls appropriate API method
  14. API executes command on the Unraid server
  15. Coordinator refreshes data to reflect changes

Factory Pattern for Entity Creation

The integration uses a factory pattern for creating entities:

[Diagram: Factory pattern class diagram showing the relationship between SensorFactory, SensorRegistry, UnraidSensorBase, and related classes]

Note: A detailed class diagram will be added in a future update.

This pattern allows for flexible entity creation:

  • Sensor types are registered once
  • Creator functions determine what entities to create
  • Factory orchestrates the creation process

Caching and Performance Optimization

The integration implements sophisticated caching to minimize SSH connections:

[Diagram: Sequence diagram showing the caching flow between Coordinator, SensorPriorityManager, CacheManager, API Client, and Unraid Server]

Note: A detailed sequence diagram will be added in a future update.

Key aspects of the caching system:

  • Different TTLs for different data types
  • Memory-efficient storage with size limits
  • Priority-based invalidation
  • Performance monitoring

Error Handling and Recovery

The integration includes robust error handling:

[Diagram: Flowchart showing the error handling process with retry logic, circuit breaking, and fallback mechanisms]

Note: A detailed flowchart will be added in a future update.

Key error handling features:

  • Exception hierarchy for different error types
  • Automatic retries with exponential backoff
  • Circuit breaking to prevent cascading failures
  • Detailed logging for troubleshooting