Framework Foundation

Framework Foundation

The framework provides reusable components, standardized patterns, and automated lifecycle management so features can focus on domain logic.

Framework architecture overview

The framework is layered:

• Base classes
• Helpers
• Services
• Card system + asset deployment

Setup framework

The setup framework (in custom_components/ramses_extras/framework/setup/) orchestrates initialization phases in a strict order and manages dependencies.

Key modules:

• entry.py (entry point + pipeline orchestrator)
• features.py (feature loading and instance creation)
• devices.py (device discovery/coordination + cleanup)
• cards.py (asset deployment and card registration)
• utils.py, yaml.py (helpers and YAML-to-config-flow bridge)

Setup pipeline phases (high level)

• Entry setup
  • initialize hass.data
  • start entity-registry monitoring
• Main setup pipeline
  • load feature definitions + import feature platforms
  • discover devices and coordinate entity setup with ramses_cc
  • deploy frontend assets and expose frontend configuration
  • register services and WebSocket commands
  • validate entities and cleanup orphaned devices
  • create and start feature instances
• Configuration updates
  • reload entry when options change
  • refresh frontend config and feature enablement state

Key design principles

• Orchestration: each phase runs in the correct order.
• Modularity: setup code is split by domain (features/devices/cards).
• Robustness: retry logic and cleanup for reliable startup.
• Flexibility: supports primary config flow and secondary YAML bootstrap.
• Real-time: monitors for updates and pushes runtime changes to the frontend.

Configuration priority

Once a config entry exists, configuration priority is:

1. Runtime data
2. Config entry (data/options)
3. YAML (only as initial bootstrap)

Base classes

• ExtrasBaseEntity (custom_components/ramses_extras/framework/base_classes/base_entity.py)
  • Base for custom entities.
• ExtrasBaseAutomation (custom_components/ramses_extras/framework/base_classes/base_automation.py)
  • Base for Python automation classes.
• Platform entity classes (custom_components/ramses_extras/framework/base_classes/platform_entities.py)
  • ExtrasSensorEntity, ExtrasSwitchEntity, ExtrasNumberEntity, ExtrasBinarySensorEntity.
• RamsesBaseCard (custom_components/ramses_extras/framework/www/ramses-base-card.js)
  • Shared base for shipped Lovelace cards.

Helper modules

Common helper areas:

• custom_components/ramses_extras/framework/helpers/config/ configuration management patterns
• custom_components/ramses_extras/framework/helpers/entity/ entity lifecycle helpers, including:
  • SimpleEntityManager
  • DeviceFeatureMatrix
• custom_components/ramses_extras/framework/helpers/service/ service registration/validation
• custom_components/ramses_extras/framework/helpers/commands/ command registry
• custom_components/ramses_extras/framework/helpers/device/ device filtering + helpers

Framework services

• Path management (custom_components/ramses_extras/framework/helpers/paths.py + custom_components/ramses_extras/framework/www/paths.js)
• Message system:
  • WebSocket command registration
  • ramses_cc message listeners + event patterns

Usage examples

Examples include:

• configuration management
• platform entities
• service framework

Back to: Home Prev: Feature System Next: Device Feature Management