How ccpk1/choreops works
1. Project boundary and runtime
- This is a Home Assistant custom integration (custom_components/choreops) that runs entirely inside the HA process.
- It is local-first: no external backend, no cloud service, and no separate database service. Persistence is handled through Home Assistant storage.
2. Primary domain
- The integration models a household operations platform with several domain areas: users/profiles, chores, scheduling, rewards, points/XP, badges, statistics, notifications, and dashboards.
- The repo supports both gamified and utility-only usage, so the architecture keeps the game layer separable from chore operations.
3. Integration entry points
- __init__.py is the integration root and likely owns setup/teardown and runtime wiring.
- config_flow.py and options_flow.py implement Home Assistant’s setup UI and runtime configuration changes.
- services.py plus services.yaml expose domain actions to automations/scripts.
- manifest.json defines the HA integration metadata and platform dependencies.
4. Layered application structure
- The managers/ package is the orchestration layer: it coordinates use cases and cross-domain workflows.
- The engines/ package appears to hold the core domain logic for chores, scheduling, economy/points, gamification, and statistics.
- The split suggests a clean boundary: managers decide “what to do,” engines compute “how it should behave.”
5. Core orchestration managers
- chore_manager, reward_manager, economy_manager, gamification_manager, statistics_manager, notification_manager, system_manager, ui_manager, and user_manager each own a major subsystem.
- These are the main application-service boundaries to show in a diagram, because they translate HA events and service calls into domain actions.
6. Domain engines
- chore_engine.py, schedule_engine.py, economy_engine.py, gamification_engine.py, and statistics_engine.py represent reusable business logic.
- The engine layer is where recurrence, rotation, streaks, badges, point accounting, and reporting rules are computed.
- This is the strongest candidate for the “core logic” box in an architecture diagram.
7. Entity and platform surface
- The integration exposes Home Assistant-native entities through sensor.py, button.py, select.py, and calendar.py, with sensor_legacy.py retained for compatibility.
- entity.py is the shared entity base, so the runtime surface is not a custom app UI only; it is also a set of HA entities that automations can consume.
- notification_action_handler.py closes the loop for actionable notifications, feeding user responses back into the domain flow.
8. State, storage, and migrations
- store.py is the persistence boundary for integration data.
- migrations/modern.py and migrations/pre_v50.py show that the project has a significant schema evolution history, including compatibility with older KidsChores data.
- integrity/boot_repairs.py indicates startup repair logic for inconsistent or partially migrated state.
- Diagram-wise, storage sits between the managers/engines and the HA entity layer.
9. Data transformation helpers
- helpers/, data_builders.py, and type_defs.py provide the translation layer between domain objects and HA-facing payloads.
- helpers/dashboard_builder.py and helpers/dashboard_helpers.py support dashboard generation, while entity_helpers.py, flow_helpers.py, storage_helpers.py, and translation_helpers.py keep setup and runtime wiring manageable.
- utils/ contains repository tooling and validation scripts, not runtime logic.
10. Dashboard subsystem
- custom_components/choreops/dashboards/ contains dashboard registry data, template YAML, preferences, and translated dashboard labels.
- The repo supports generated or templated dashboards for different personas and layouts, including admin/shared/user variants.
- This subsystem is a separate presentation layer that consumes runtime state and helper payloads rather than duplicating business logic.
11. Localization and branding
- translations/ and translations_custom/ provide integration text plus specialized notification/report strings.
- Dashboard-specific translations live separately under the dashboards package.
- brand/, icons.json, and related assets support consistent Home Assistant presentation and entity naming.
12. Testing and validation model
- The tests/ tree is extensive and scenario-driven, with fixtures, migration samples, golden master data, and end-to-end workflow tests.
- Coverage spans config flows, services, entity behavior, scheduling, gamification, notifications, dashboard generation, migration, and performance.
- This means the architecture is not just layered in code; it is also enforced by contract and scenario tests across the major boundaries.
13. Operational and release tooling
- GitHub Actions, pre-commit, lint/type configs, and HACS metadata show that the repo is built for strict quality gates and Home Assistant distribution.
- The presence of release, validation, and dashboard asset workflows indicates the repo treats generated assets and integration packaging as part of the architecture, not just build plumbing.
14. End-to-end data flow
- A typical flow is: Home Assistant config/options → stored integration state → managers/orchestrators → domain engines → updated storage and entity state → dashboards, sensors, actions, and notifications.
- User actions can re-enter through services, entity commands, or notification responses, making the system a closed loop inside Home Assistant rather than a one-way data publisher.
Main entry points: store.py Store · entity.py Entities · services.py Services · README.md Tests
Components 34
HA integration
Home Assistant entry points and entity surface
- Integration · Home Assistant integration root and lifecycle wiring
custom_components/choreops/__init__.py - Config flow · Initial setup and discovery flow
custom_components/choreops/config_flow.py - Options flow · Runtime configuration changes
custom_components/choreops/options_flow.py - Services · Service registration and automation actions
custom_components/choreops/services.py - Action handler · Routes actionable notification responses back into workflows
custom_components/choreops/notification_action_handler.py
Application layer
Orchestration managers and service boundaries
- UI manager · Coordinates dashboard and control-state presentation
custom_components/choreops/managers/ui_manager.py - System manager · Owns startup, cleanup, and integration-wide coordination
custom_components/choreops/managers/system_manager.py - User manager · Manages household users, roles, and profile state
custom_components/choreops/managers/user_manager.py - Chore manager · Coordinates chore lifecycle and cross-domain updates
custom_components/choreops/managers/chore_manager.py - Reward manager · Handles reward CRUD and redemption workflows
custom_components/choreops/managers/reward_manager.py - Economy manager · Coordinates points, XP, and accounting flows
custom_components/choreops/managers/economy_manager.py - Gamify manager · Coordinates badges, streaks, and progression flows
custom_components/choreops/managers/gamification_manager.py - Stats manager · Builds rollups and reporting workflows
custom_components/choreops/managers/statistics_manager.py - Notification manager · Sends reminders and notification updates
custom_components/choreops/managers/notification_manager.py
Domain engines
Core business rules for chores, schedules, economy, gamification, and stats
- Chore engine · Rules for chore state, availability, and completion
custom_components/choreops/engines/chore_engine.py - Schedule engine · Recurrence, rotation, streak, and due-date rules
custom_components/choreops/engines/schedule_engine.py - Economy engine · Points and XP calculations
custom_components/choreops/engines/economy_engine.py - Gamify engine · Badges, streaks, and game-state computation
custom_components/choreops/engines/gamification_engine.py - Stats engine · Reporting and aggregate statistics computation
custom_components/choreops/engines/statistics_engine.py
State & migration
Persistence, repair, and schema evolution
- Store · Home Assistant storage boundary for integration state
custom_components/choreops/store.py - Migrations · Modern and legacy data migration paths
custom_components/choreops/migrations/modern.py - Boot repairs · Repairs inconsistent or partially migrated state
custom_components/choreops/integrity/boot_repairs.py
Presentation
Dashboards, entities, translations, and branding
- Entities · Shared entity base and integration surface
custom_components/choreops/entity.py - Sensors · State exposure for automations and dashboards
custom_components/choreops/sensor.py - Legacy sensors · Backwards-compatible sensor platform
custom_components/choreops/sensor_legacy.py - Buttons · User-triggered control entities
custom_components/choreops/button.py - Selects · Choice and mode entities
custom_components/choreops/select.py - Calendar · Schedule-facing calendar entity
custom_components/choreops/calendar.py - Helpers · Shared adapters between domain objects and HA payloads
custom_components/choreops/helpers/__init__.py - Dashboard builder · Builds dashboard content from runtime state
custom_components/choreops/helpers/dashboard_builder.py - Dashboards · Registry, templates, preferences, and dashboard translations
custom_components/choreops/dashboards/dashboard_registry.json - Translations · Integration text and custom notification/report strings
custom_components/choreops/translations/en.json - Branding · Brand assets and icon metadata for HA presentation
custom_components/choreops/brand
Tooling & QA
Repository validation, release, and tests
- Tests · Scenario, migration, entity, service, and workflow coverage
tests/README.md
Connections 41
- Config flow → Store: creates state · Initial setup writes integration state
- Options flow → Store: updates state · Runtime options are persisted
- Integration → System manager: wires lifecycle · Setup and teardown coordination
- Integration → Services: registers · Exposes HA services on setup
- Integration → Entities: registers entities · Attaches platform entities
- Services → Chore manager: dispatches · Service calls enter chore workflows
- Services → Reward manager: dispatches · Service calls enter reward workflows
- Services → Economy manager: dispatches · Service calls enter points workflows
- Services → Gamify manager: dispatches · Service calls enter game workflows
- Services → Stats manager: dispatches · Service calls enter reporting workflows
- Action handler → Notification manager: feeds back · Action responses re-enter notification workflows
- Chore manager → Chore engine: uses · Delegates chore rules to domain logic
- Chore manager → Schedule engine: uses · Delegates scheduling and recurrence rules
- Reward manager → Economy engine: uses · Reward costs and payouts affect economy rules
- Economy manager → Economy engine: uses · Points and XP calculations
- Gamify manager → Gamify engine: uses · Badge and progression logic
- Stats manager → Stats engine: uses · Rollups and reporting aggregates
- System manager → Store: loads/saves · Owns state persistence lifecycle
- Store → Migrations: evolves via · Storage schema is migrated across versions
- System manager → Boot repairs: repairs · Startup repair handles inconsistent state
- Helpers → Dashboard builder: supports · Helper layer feeds dashboard generation
- Dashboard builder → Dashboards: renders · Generated payloads populate templates and registry
- UI manager → Dashboard builder: coordinates · Presentation orchestration for dashboards and controls
- UI manager → Entities: syncs · Keeps UI state aligned with entities
- Entities → Sensors: implements · Primary sensor surface
- Entities → Buttons: implements · Button control surface
- Entities → Selects: implements · Select control surface
- Entities → Calendar: implements · Calendar surface
- Entities → Legacy sensors: compatibility · Legacy sensor support remains available
- Chore manager → Store: persists · Chore updates are written back to storage
- Economy manager → Store: persists · Points/accounting state is stored
- Gamify manager → Store: persists · Progression state is stored
- Stats manager → Store: reads · Reports consume stored operational data
- Translations → Dashboards: localizes · Dashboard text is translated separately
- Branding → Entities: brands · Brand assets shape HA presentation
- Tests → Config flow: covers · Setup flow contract tests
- Tests → Services: covers · Service and action contract tests
- Tests → Store: covers · Persistence and migration tests
- Tests → Dashboards: covers · Dashboard generation and template tests
- Tests → Chore engine: covers · Domain logic regression tests
- Tests → Gamify engine: covers · Game logic regression tests