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.HomeKeeperConfigFlowsets a fixed unique id. - Settings for a companion integration (companions-presets).
Design
Module map
| Layer | Modules | Rule |
|---|---|---|
| Pure core | recurrence.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 catalogs | No homeassistant import. Time and zone come in as arguments. |
| Boundary | options.py, coordinator.py, device_compat.py, notifier.py, card.py, sensor_watcher.py, tag_listener.py, photo_thumbs.py, panel_tabs.py | Home 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 modules | Talks to Home Assistant and calls into the core. |
| Platforms | todo.py, calendar.py, button.py, sensor.py, binary_sensor.py, number.py, event.py, trigger.py, device_trigger.py | const.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:
- 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). - Create
HomeKeeperCoordinator, refresh it, and store it asentry.runtime_data. - Reconcile asset devices, part tasks, buy tasks, problem sensors and declarative companions, so the tasks exist before the platforms read them.
- Register the panel, the card, the HTTP views and the websocket commands. Remove stale
photo and import folders. Forward
const.PLATFORMSand prune devices with no entities. - Ask companions to register again. Add the options listener and the language listener.
- Start the sensor watcher. Start the list syncs when the Home Assistant start is done.
- 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_optionsand the panel send a partial update tooptions.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 forasync_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 returnsoptions.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
| Doc | Subject |
|---|---|
| recurrence | Recurrence types and the next-due calculation |
| store | The storage document and the mutation chokepoint |
| coordinator-entities | The coordinator, the platforms and device links |
| appliances | Assets, virtual devices, parts and stock |
| completions | Completion, skip and snooze records |
| documents-photos | Appliance documents, completion photos and signed URLs |
| task-photos | Photos on a task, thumbnails and the cover |
| sensor-tasks | Tasks driven by sensors, meters and problem sensors |
| companions-presets | Companion discovery and declarative presets |
| profiles-notifications | Profiles and notifications |
| sync | Shopping-list and to-do list syncs |
| events-api | Events, triggers and the API surface model |
| transfer | Import and export |
| frontend | The panel and the dashboard card |
| qr-labels | QR code labels that link to a panel page |
| cost-summary | Maintenance 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_setupover 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 inentry.options(const.OPTION_*). Automations callhome_keeper.set_optionsby key. - Service names and fields, in the API surface model (INTEGRATING.md).