Directory Structure

Directory Structure

This page documents the complete directory structure of the Ramses Extras integration.

Overview

The integration follows a feature-centric architecture with clear separation between core integration requirements, individual features, and reusable framework components.

Complete Structure

custom_components/ramses_extras/
├── 🔑 Core Integration (HA Requirements)
│   ├── __init__.py              # Integration entry point
│   ├── config_flow.py           # HA config flow
│   ├── const.py                 # Core constants with AVAILABLE_FEATURES
│   ├── manifest.json            # HA integration manifest
│   └── services.yaml            # HA service definitions
│
├── 🎯 Features (Feature-Centric)
│   ├── humidity_control/        # Humidity control feature
│   │   ├── automation.py        # Feature automation logic
│   │   ├── services.py          # Feature services
│   │   ├── entities.py          # Entity management
│   │   ├── config.py            # Feature configuration
│   │   ├── const.py             # Feature constants
│   │   ├── __init__.py          # Feature factory
│   │   └── platforms/           # HA platform implementations
│   │       ├── sensor.py        # Feature sensor entities
│   │       ├── switch.py        # Feature switch entities
│   │       ├── number.py        # Feature number entities
│   │       └── binary_sensor.py # Feature binary sensor entities
│   │
│   ├── sensor_control/          # Sensor source mapping and zone configuration
│   │   ├── __init__.py
│   │   ├── const.py
│   │   ├── config_flow.py       # Feature-specific config flow helper
│   │   ├── resolver.py          # SensorControlResolver implementation
│   │   ├── zones_yaml.py        # Zone configuration handling
│   │   ├── device_types/        # Per-device-type config handlers
│   │   └── www/                 # FAN Map web assets
│   │       └── sensor_control/
│   │           ├── fan-map.js
│   │           ├── fan-map-editor.js
│   │           └── translations/
│   │
│   ├── hvac_fan_card/           # HVAC fan card feature
│   │   ├── __init__.py
│   │   ├── const.py
│   │   └── www/                 # Feature-specific web assets
│   │       └── hvac_fan_card/
│   │           ├── hvac-fan-card.js
│   │           ├── hvac-fan-card-editor.js
│   │           ├── message-handlers.js
│   │           └── translations/
│   │
│   ├── ramses_debugger/         # Debugging tools
│   │   ├── __init__.py
│   │   ├── const.py
│   │   ├── traffic_collector.py # Real-time traffic analysis
│   │   ├── websocket_commands.py# Debugger WebSocket APIs
│   │   └── www/                 # Debugger UI cards
│   │       └── ramses_debugger/
│   │           ├── traffic-analyzer.js
│   │           ├── log-explorer.js
│   │           └── packet-log-explorer.js
│   │
│   ├── hello_world/             # Hello World template feature
│   │   ├── __init__.py
│   │   ├── automation.py
│   │   ├── config.py
│   │   ├── const.py
│   │   ├── entities.py
│   │   ├── services.py
│   │   ├── websocket_commands.py
│   │   ├── platforms/
│   │   │   ├── __init__.py
│   │   │   ├── binary_sensor.py
│   │   │   ├── number.py
│   │   │   ├── sensor.py
│   │   │   └── switch.py
│   │   └── www/
│   │       └── hello_world/
│   │           ├── card-styles.js
│   │           ├── hello-world-editor.js
│   │           ├── hello-world.js
│   │           ├── templates/
│   │           └── translations/
│   │               ├── en.json
│   │               └── nl.json
│   │
│   └── default/                 # Default feature scaffold
│       ├── __init__.py
│       ├── const.py
│       ├── commands.py
│       ├── config_flow.py
│       ├── websocket_commands.py
│       └── platforms/
│           └── sensor.py
│
├── 🏛️ Framework (Reusable Foundation)
│   ├── setup/                   # Setup and orchestration framework
│   │   ├── __init__.py
│   │   ├── entry.py             # Main entry point and setup pipeline
│   │   ├── features.py          # Feature loading and management
│   │   ├── devices.py           # Device discovery and management
│   │   ├── cards.py             # Lovelace card deployment
│   │   ├── utils.py             # Setup utilities
│   │   └── yaml.py              # YAML-to-config-flow bridge
│   │
│   ├── base_classes/            # Base classes for inheritance
│   │   ├── __init__.py
│   │   ├── base_automation.py   # Automation base
│   │   ├── base_entity.py       # Entity base
│   │   └── platform_entities.py # Generic platform entities
│   │
│   ├── helpers/                 # Reusable Python utilities
│   │   ├── __init__.py
│   │   ├── config/              # Configuration management
│   │   │   ├── __init__.py
│   │   │   ├── core.py          # ExtrasConfigManager
│   │   │   ├── validation.py    # ConfigValidator
│   │   │   ├── schema.py        # ConfigSchema
│   │   │   └── templates.py     # ConfigTemplates
│   │   ├── config_flow.py       # Config flow extension helpers
│   │   ├── platform.py          # Enhanced with setup framework
│   │   ├── brand_customization/ # Brand customization
│   │   │   ├── __init__.py
│   │   │   ├── core.py          # ExtrasBrandCustomizer
│   │   │   ├── detection.py     # BrandPatterns
│   │   │   ├── models.py        # ModelConfigManager
│   │   │   └── entities.py      # EntityGenerationManager
│   │   ├── entity/              # Entity management
│   │   │   ├── __init__.py
│   │   │   ├── core.py          # EntityHelpers
│   │   │   ├── simple_entity_manager.py # SimpleEntityManager
│   │   │   ├── device_feature_matrix.py # DeviceFeatureMatrix
│   │   │   └── device_feature_mapping.py # Legacy mapping
│   │   ├── service/             # Service framework
│   │   │   ├── __init__.py
│   │   │   ├── core.py          # ExtrasServiceManager
│   │   │   ├── registration.py  # ServiceRegistry
│   │   │   └── validation.py    # ServiceValidator
│   │   ├── automation/          # Automation helpers
│   │   ├── device/              # Device helpers
│   │   │   ├── __init__.py
│   │   │   ├── core.py          # Device helpers
│   │   │   └── filter.py        # Device filtering
│   │   ├── commands/            # Command framework
│   │   │   ├── __init__.py
│   │   │   └── registry.py      # CommandRegistry
│   │   ├── common/              # Common utilities
│   │   │   ├── __init__.py
│   │   │   └── validation.py    # Validation utilities
│   │   └── paths.py             # Path management
│   │
│   ├── www/                     # Reusable JavaScript utilities
│   │   ├── paths.js             # Environment-aware path constants
│   │   ├── card-commands.js
│   │   ├── card-services.js
│   │   ├── card-translations.js
│   │   ├── card-validation.js
│   │   └── ramses-message-broker.js
│   │
│   └── managers/                # Framework managers
│       └── __init__.py
│
├── 🌐 Platform (HA Integration)
│   ├── sensor.py                # Root sensor platform
│   ├── switch.py                # Root switch platform
│   ├── binary_sensor.py         # Root binary sensor platform
│   ├── number.py                # Root number platform
│   └── __init__.py
│
├── extras_registry.py           # Feature registry system
├── websocket_integration.py     # WebSocket command registry
└── translations/                # Integration-level translations
    ├── en.json                  # English integration strings
    └── nl.json                  # Dutch integration strings

Key Directories

Core Integration

Contains the minimum required files for Home Assistant integration registration and configuration.

Features

Each feature is self-contained with its own:

• Automation logic (Python-based, not YAML)
• Services
• Entities
• Configuration
• Platform implementations
• Web assets (cards, editors, translations)

Framework

Provides reusable components that all features can use:

• Setup: Orchestrated initialization and lifecycle management
• Base Classes: Common base classes for entities and automation
• Helpers: Utilities for configuration, entities, services, devices, etc.
• www: Shared JavaScript utilities for frontend cards

Platform

Thin wrapper files that forward to feature-specific implementations.

Back to: Home

Prev: Advanced Settings Next: Development Guide