Skip to main content

Architecture

Home Keeper is a Home Assistant integration that tracks home maintenance and chores. Administrators manage tasks and appliances in a sidebar panel. All household members use the tasks through native entities, such as the to-do list and the calendar, and the panel.

Goals​

  • G1. Testable core. The rules for schedules, tasks, assets and options run without Home Assistant, so the fast unit tier and the mutation gate can check them.
  • G2. Native usage. Daily use goes through native entities. The panel is for administration. Other users can open it to use the tasks and read the appliances.
  • G3. One privilege line. Writes to appliances and settings are admin-only. Usage is open.
  • G4. Services first. Each data action is a home_keeper.* service, so automations, scripts, voice and other integrations can do what the panel does.
  • G5. Safe reloads. A reload keeps services, the panel and saved options intact.

Non-goals​

  • Administration in the dashboard card. The card is a usage surface (frontend).
  • More than 1 config entry. config_flow.HomeKeeperConfigFlow sets a fixed unique id.
  • Settings for a companion integration (companions-presets).

Design​

Module map​

LayerModulesRule
Pure corerecurrence.py, models.py, assets.py, events.py, transitions.py, profiles.py, notifications.py, transfer.py, transfer_bundle.py, reconcile.py, sensor_tasks.py, problem_tasks.py, cost_summary.py, shopping.py, todo_items.py, task_photos.py, trigger_targets.py, deprecations.py, const.py, the catalogsNo homeassistant import. Time and zone come in as arguments.
Boundaryoptions.py, coordinator.py, device_compat.py, notifier.py, card.py, sensor_watcher.py, tag_listener.py, photo_thumbs.py, panel_tabs.pyHome Assistant imports only under TYPE_CHECKING.
Glue__init__.py, store.py, devices.py, websocket_api.py, panel.py, config_flow.py, diagnostics.py, manuals.py, transfer_runner.py, transfer_http.py, companions.py, the sync modulesTalks to Home Assistant and calls into the core.
Platformstodo.py, calendar.py, button.py, sensor.py, binary_sensor.py, number.py, event.py, trigger.py, device_trigger.pyconst.PLATFORMS lists the entity platforms.

The mutation allowlist (only_mutate in pyproject.toml) is drawn from the first 2 rows. api_surface.py declares each surface that an integrator sees (events-api).

Administration, usage and privilege​

panel.async_register_panel registers a custom panel at /home-keeper with require_admin=False. It serves only frontend/dist/, because Home Assistant serves static paths before authentication. panel.cache_token hashes the bundle into its URL. A non-admin uses tasks from the native entities, the card and the panel, and reads the appliances in the panel (SECURITY.md).

A websocket command and its service twin are the same operation. An admin-only operation has @websocket_api.require_admin on the command, and its service handler calls the local _verify_admin, which raises the bare Unauthorized. A call with no context.user_id comes from an automation or from the core and is trusted. The gate covers appliance edits, asset documents, part files and stock, declarative companion edits, register_companion, orphan and archive deletes, set_options, the appliance report, export and import with their HTTP views, list_entity_keys and the companion preview. Else open.

Setup​

async_setup calls _register_services 1 time for each Home Assistant run, so services stay through reloads. A handler raises integration_not_loaded when no entry is loaded. Each websocket command calls the same store method as its service twin. async_setup_entry then runs these steps in order:

  1. Load the backend strings, then HomeKeeperStore, and apply the set due time (store.async_apply_due_time). Repair split device ids (devices.async_heal_split_device_ids).
  2. Create HomeKeeperCoordinator, refresh it, and store it as entry.runtime_data.
  3. Reconcile asset devices, part tasks, buy tasks, problem sensors and declarative companions, so the tasks exist before the platforms read them.
  4. Register the panel, the card, the HTTP views and the websocket commands. Remove stale photo and import folders. Forward const.PLATFORMS and prune devices with no entities.
  5. Ask companions to register again. Add the options listener and the language listener.
  6. Start the sensor watcher. Start the list syncs when the Home Assistant start is done.
  7. Enable transition events, start the 5-minute clock, refresh 1 more time, and set the companion registry live after start.

A failure in the repair or the prune is logged and does not stop setup.

Unload and remove​

async_unload_entry unloads the platforms and discards edge state for a disabled entry. It closes the store so that a pass from before the unload cannot write over a new store. It removes the panel only for a disabled entry, because a reload with no panel sends an open page to the default dashboard. async_remove_entry removes the panel, the companion tabs, the card resource, the storage document and the uploaded files.

Config entry and options​

The config flow is 1 confirmation step with no data. options.py defines every option key and default (options.ALL_OPTIONS). The options flow, set_options and Settings edit them.

  • set_options and the panel send a partial update to options.async_set_options. It merges, ignores a list option sent as a value that is not a list, refuses a save that strands a notification (options.ProfileInUseError), writes, and waits for async_apply_options (rules), or for a reload with no coordinator.
  • Home Assistant stores an options flow result as the whole options object. The form shows only options.FLOW_OPTIONS, so the flow returns options.merge_flow_input: a cleared form key resets, and a key outside the form keeps its value.

Diagnostics​

diagnostics.py dumps the tasks and assets for the entry or for 1 device. It removes the keys in diagnostics.TO_REDACT, because users attach dumps to public issues.

Design doc index​

DocSubject
recurrenceRecurrence types and the next-due calculation
storeThe storage document and the mutation chokepoint
coordinator-entitiesThe coordinator, the platforms and device links
appliancesAssets, virtual devices, parts and stock
completionsCompletion, skip and snooze records
documents-photosAppliance documents, completion photos and signed URLs
task-photosPhotos on a task, thumbnails and the cover
sensor-tasksTasks driven by sensors, meters and problem sensors
companions-presetsCompanion discovery and declarative presets
profiles-notificationsProfiles and notifications
syncShopping-list and to-do list syncs
events-apiEvents, triggers and the API surface model
transferImport and export
frontendThe panel and the dashboard card
qr-labelsQR code labels that link to a panel page
cost-summaryMaintenance spend and appliance purchase totals

Trade-offs​

  • A sidebar panel over a dashboard card for administration: management is a full-page activity with forms and pickers, and native cards already do usage well.
  • Services registered in async_setup over per-entry services: a call during a reload gets a clear error, not "action not found".
  • A live apply when the entity set stays over a reload on each options change: a reload makes each entity unavailable in the logbook. Cost: options._APPLY_STEPS.

One-way doors​

  • The domain home_keeper, the panel path /home-keeper, and the option keys in entry.options (const.OPTION_*). Automations call home_keeper.set_options by key.
  • Service names and fields, in the API surface model (INTEGRATING.md).