# jvarhol/ha-family-hub architecture

> Architecture diagram of the GitHub repository jvarhol/ha-family-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jvarhol/ha-family-hub
- Repository: https://github.com/jvarhol/ha-family-hub

## Overview

Family Hub is a self-hosted Home Assistant integration for a family-tablet dashboard. People use its cards for calendar and meal planning, household tasks, and device-specific presentation; the chores/rewards/routines board is served by a websocket API and backend domain engines. The README documents additional calendar, pantry, privacy, notification, and theming capabilities. Several backend relationships below are documented or visible in the source index, but unsampled runtime wiring is not assumed.

Main entry points: [`custom_components/family_hub/chores_websocket_api.py`](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/chores_websocket_api.py) (Chores Websocket API), [`custom_components/family_hub/reward_engine.py`](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/reward_engine.py) (Reward Engine), [`custom_components/family_hub/chore_engine.py`](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/chore_engine.py) (Chore Engine), [`custom_components/family_hub/card/family-week-calendar-card.js`](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-week-calendar-card.js) (Week Calendar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Family Dashboard"]
  node_week["Week Calendar"]
  node_today["Today Card"]
  node_todo["To-do Card"]
  node_recipe["Recipe Box"]
  node_pantry["Pantry Card"]
end

subgraph group_household["Household Activities"]
  node_chores_ui["Chores Board"]
  node_mychores["My Chores"]
  node_rewards_ui["Rewards Board"]
  node_goals_ui["Goals Board"]
  node_timers_ui["Active Timers"]
end

subgraph group_backend["Integration Backend"]
  node_chores_api["Chores Websocket API"]
  node_chore_engine["Chore Engine<br/>[chore_engine.py]"]
  node_goal_engine["Goal Engine<br/>[goal_engine.py]"]
  node_reward_engine["Reward Engine<br/>[reward_engine.py]"]
  node_routine_engine["Routine Engine<br/>[routine_engine.py]"]
  node_timer_engine["Timer Engine<br/>[timer_engine.py]"]
  node_store[("Persistent Stores<br/>[store.py]")]
  node_pantry_engine["Pantry Engine<br/>[pantry_engine.py]"]
  node_grocery["Grocery References"]
  node_integration["Integration Setup<br/>[__init__.py]"]
  node_notifications["Scheduled Notifications<br/>[__init__.py]"]
end

subgraph group_device["Device Experience"]
  node_screensaver["Screen Saver"]
  node_theme_builder["Theme Builder"]
  node_theme_selector["Theme Selector"]
  node_device_api["Device Settings API"]
  node_device_entities["Device Settings Entities"]
end

node_family(("Household members"))
node_ha["Home Assistant"]
node_calendars[("Calendar entities")]

node_family -->|"uses"| node_week
node_family -->|"uses"| node_today
node_family -->|"uses"| node_todo
node_family -->|"uses"| node_recipe
node_family -->|"uses"| node_pantry
node_family -->|"uses"| node_chores_ui
node_family -->|"uses"| node_mychores
node_family -->|"uses"| node_rewards_ui
node_family -->|"uses"| node_goals_ui
node_family -->|"uses"| node_timers_ui
node_family -->|"uses"| node_screensaver
node_family -->|"uses"| node_theme_selector
node_week -->|"reads events"| node_calendars
node_chores_ui -->|"uses websocket"| node_chores_api
node_mychores -->|"uses websocket"| node_chores_api
node_rewards_ui -->|"uses websocket"| node_chores_api
node_chores_api -->|"dispatches"| node_chore_engine
node_chores_api -->|"dispatches"| node_goal_engine
node_chores_api -->|"dispatches"| node_reward_engine
node_chores_api -->|"dispatches"| node_routine_engine
node_chores_api -->|"dispatches"| node_timer_engine
node_chores_api -.->|"loads and saves"| node_store
node_device_api -->|"syncs entities"| node_device_entities
node_chore_engine -.->|"uses timers"| node_timer_engine
node_chore_engine -.->|"uses rewards"| node_reward_engine
node_goal_engine -.->|"uses rewards"| node_reward_engine
node_routine_engine -->|"awards stars"| node_reward_engine
node_family -->|"customizes themes"| node_theme_builder
node_ha -->|"hosts"| node_integration
node_integration -.->|"schedules"| node_notifications
node_pantry -.->|"optional integration"| node_grocery
node_ha -.->|"optional Grocy data"| node_pantry_engine

click node_week "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-week-calendar-card.js"
click node_today "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-today-card.js"
click node_todo "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-todo-card.js"
click node_recipe "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-recipe-box-card.js"
click node_pantry "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-pantry-card.js"
click node_chores_ui "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-chores-card.js"
click node_mychores "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-my-chores-card.js"
click node_rewards_ui "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-rewards-card.js"
click node_goals_ui "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-goals-card.js"
click node_timers_ui "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-active-timers-card.js"
click node_screensaver "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-screensaver-card.js"
click node_theme_builder "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/panel/theme-builder-panel.js"
click node_theme_selector "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/panel/theme-selector-card.js"
click node_chores_api "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/chores_websocket_api.py"
click node_chore_engine "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/chore_engine.py"
click node_goal_engine "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/goal_engine.py"
click node_reward_engine "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/reward_engine.py"
click node_routine_engine "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/routine_engine.py"
click node_timer_engine "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/timer_engine.py"
click node_store "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/store.py"
click node_pantry_engine "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/pantry_engine.py"
click node_grocery "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/grocery_reference.py"
click node_device_api "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/device_settings_websocket_api.py"
click node_device_entities "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/device_settings_entity_shared.py"
click node_integration "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/__init__.py"
click node_notifications "https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_week,node_today,node_todo,node_recipe,node_pantry toneBlue
class node_chores_ui,node_mychores,node_rewards_ui,node_goals_ui,node_timers_ui,node_calendars toneAmber
class node_chores_api,node_chore_engine,node_goal_engine,node_reward_engine,node_routine_engine,node_timer_engine,node_store,node_pantry_engine,node_grocery,node_integration,node_notifications toneMint
class node_screensaver,node_theme_builder,node_theme_selector,node_device_api,node_device_entities toneRose
class node_family,node_ha toneIndigo
```

## Components

### Family Dashboard

- [Week Calendar](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-week-calendar-card.js): `custom_components/family_hub/card/family-week-calendar-card.js`
- [Today Card](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-today-card.js): `custom_components/family_hub/card/family-today-card.js`
- [To-do Card](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-todo-card.js): `custom_components/family_hub/card/family-hub-todo-card.js`
- [Recipe Box](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-recipe-box-card.js): `custom_components/family_hub/card/family-hub-recipe-box-card.js`
- [Pantry Card](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-pantry-card.js): `custom_components/family_hub/card/family-hub-pantry-card.js`

### Household Activities

- [Chores Board](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-chores-card.js): `custom_components/family_hub/card/family-hub-chores-card.js`
- [My Chores](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-my-chores-card.js): `custom_components/family_hub/card/family-hub-my-chores-card.js`
- [Rewards Board](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-rewards-card.js): `custom_components/family_hub/card/family-hub-rewards-card.js`
- [Goals Board](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-goals-card.js): `custom_components/family_hub/card/family-hub-goals-card.js`
- [Active Timers](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-hub-active-timers-card.js): `custom_components/family_hub/card/family-hub-active-timers-card.js`

### Integration Backend

- [Chores Websocket API](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/chores_websocket_api.py): `custom_components/family_hub/chores_websocket_api.py`
- [Chore Engine](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/chore_engine.py): `custom_components/family_hub/chore_engine.py`
- [Goal Engine](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/goal_engine.py): `custom_components/family_hub/goal_engine.py`
- [Reward Engine](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/reward_engine.py): `custom_components/family_hub/reward_engine.py`
- [Routine Engine](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/routine_engine.py): `custom_components/family_hub/routine_engine.py`
- [Timer Engine](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/timer_engine.py): `custom_components/family_hub/timer_engine.py`
- [Persistent Stores](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/store.py): `custom_components/family_hub/store.py`
- [Pantry Engine](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/pantry_engine.py): `custom_components/family_hub/pantry_engine.py`
- [Grocery References](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/grocery_reference.py): `custom_components/family_hub/grocery_reference.py`
- [Integration Setup](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/__init__.py): `custom_components/family_hub/__init__.py`
- [Scheduled Notifications](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/__init__.py): `custom_components/family_hub/__init__.py`

### Device Experience

- [Screen Saver](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/card/family-screensaver-card.js): `custom_components/family_hub/card/family-screensaver-card.js`
- [Theme Builder](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/panel/theme-builder-panel.js): `custom_components/family_hub/panel/theme-builder-panel.js`
- [Theme Selector](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/panel/theme-selector-card.js): `custom_components/family_hub/panel/theme-selector-card.js`
- [Device Settings API](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/device_settings_websocket_api.py): `custom_components/family_hub/device_settings_websocket_api.py`
- [Device Settings Entities](https://github.com/jvarhol/ha-family-hub/blob/main/custom_components/family_hub/device_settings_entity_shared.py): `custom_components/family_hub/device_settings_entity_shared.py`

### Other components

- **Household members**
- **Home Assistant**
- **Calendar entities**

## Connections

- Household members → Week Calendar: uses (evidence: `README.md`)
- Household members → Today Card: uses (evidence: `README.md`)
- Household members → To-do Card: uses (evidence: `README.md`)
- Household members → Recipe Box: uses (evidence: `README.md`)
- Household members → Pantry Card: uses (evidence: `README.md`)
- Household members → Chores Board: uses (evidence: `README.md`)
- Household members → My Chores: uses (evidence: `README.md`)
- Household members → Rewards Board: uses (evidence: `README.md`)
- Household members → Goals Board: uses (evidence: `README.md`)
- Household members → Active Timers: uses (evidence: `README.md`)
- Household members → Screen Saver: uses (evidence: `README.md`)
- Household members → Theme Selector: uses (evidence: `README.md`)
- Week Calendar → Calendar entities: reads events (evidence: `README.md`)
- Chores Board → Chores Websocket API: uses websocket (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- My Chores → Chores Websocket API: uses websocket (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Rewards Board → Chores Websocket API: uses websocket (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Chores Websocket API → Chore Engine: dispatches (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Chores Websocket API → Goal Engine: dispatches (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Chores Websocket API → Reward Engine: dispatches (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Chores Websocket API → Routine Engine: dispatches (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Chores Websocket API → Timer Engine: dispatches (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Chores Websocket API → Persistent Stores: loads and saves (evidence: `custom_components/family_hub/chores_websocket_api.py`)
- Device Settings API → Device Settings Entities: syncs entities (evidence: `custom_components/family_hub/device_settings_websocket_api.py`)
- Chore Engine → Timer Engine: uses timers (evidence: `custom_components/family_hub/chore_engine.py`)
- Chore Engine → Reward Engine: uses rewards (evidence: `custom_components/family_hub/chore_engine.py`)
- Goal Engine → Reward Engine: uses rewards (evidence: `custom_components/family_hub/goal_engine.py`)
- Routine Engine → Reward Engine: awards stars (evidence: `custom_components/family_hub/routine_engine.py`)
- Household members → Theme Builder: customizes themes (evidence: `README.md`)
- Home Assistant → Integration Setup: hosts (evidence: `README.md`)
- Integration Setup → Scheduled Notifications: schedules
- Pantry Card → Grocery References: optional integration
- Home Assistant → Pantry Engine: optional Grocy data
