Technical: Configuration - ad-ha/kidschores-ha GitHub Wiki

1. Architecture Overview

  • Config Flow (config_flow.py): Used for initial installation and data recovery. It creates the ConfigEntry. It uses a sequential "Count -> Loop" pattern to batch-create entities during setup.
  • Options Flow (options_flow.py): Used for ongoing management (Configure button). It uses a "Menu -> Action" pattern to Add, Edit, or Delete specific entities one by one.
  • Flow Helpers (flow_helpers.py): The "Source of Truth." Both flows call into this file to generate UI schemas (build_*_schema) and validate data (validate_*_inputs). This ensures that a Chore looks the same whether created during setup or added 6 months later.

2. Trace: The Config Flow (First Time Setup)

The Config Flow is linear. It assumes the user wants to set up the system from scratch or restore a backup.

Entry Point: async_step_user

  1. Data Recovery (async_step_data_recovery)

    • Check: Scans .storage for existing data or backups.
    • Options:
      • Start Fresh: Wipes data, creates a safety backup, proceeds to setup.
      • Use Current Active: Keeps existing data (if reinstalling), skips setup wizard.
      • Restore Backup: Selects a specific JSON backup file.
      • Paste JSON: Manual data restoration.

  2. System Basics

    • Intro: Welcome screen.
    • Points Label: Sets the currency name (e.g., "Points", "Stars", "Gold") and icon.
      • Helper: fh.build_points_schema, fh.validate_points_inputs.

  3. Entity Loops (The "Count -> Define" Pattern)

    • Logic: The flow asks "How many [X]?", then loops that many times collecting details for [X].
    • Kids:
      • Step: kid_count -> kids (Loop).
      • Helper: fh.build_kid_schema.
    • Parents:
      • Step: parent_count -> parents (Loop).
      • Helper: fh.build_parent_schema.
    • Chores:
      • Step: chore_count -> chores (Loop).
      • Helper: fh.build_chore_schema (Populates assigned_kids dropdown dynamically).
    • Badges, Rewards, Penalties, Bonuses, Achievements, Challenges:
      • Follows the exact same pattern: Ask Count -> Loop Schema -> Save to Temp Dict.

  4. Finish (async_step_finish)

    • Summary: Displays a summary of all created entities.
    • Action: Writes all temporary data directly to storage_manager and creates the Config Entry.

  5. Reconfigure (async_step_reconfigure)

    • Trigger: User clicks "Reconfigure" on the integration entry (not "Configure").
    • Action: Allows editing System Settings (Points label, Update Interval, Retention).
    • Helper: fh.build_all_system_settings_schema.

3. Trace: The Options Flow (Ongoing Management)

The Options Flow is menu-driven.

Entry Point: async_step_init (The Main Menu)

Main Menu Options:

  1. Manage General Options

    • Schema: fh.build_general_options_schema.
    • Settings: Update Interval, Calendar Lookahead, Data Retention (Daily/Weekly/Monthly/Yearly), Legacy Entity Toggle, Backup Retention limits.

  2. Manage Points

    • Action: Edit the label and icon for points.

  3. Manage [Entity] (Kids, Chores, Rewards, etc.)

    • Step 1: Select Action (add, edit, delete).
    • Step 2 (If Add):
      • Calls async_step_add_[entity].
      • Uses fh.build_[entity]_schema to render the form.
      • Uses fh.validate_[entity]_inputs to check data.
      • Uses fh.build_[entity]_data to format for storage.
      • Calls Coordinator to persist data immediately.
    • Step 2 (If Edit/Delete):
      • Calls async_step_select_entity.
      • User picks an entity from a dropdown (filtered by type).
      • If Edit: Pre-fills the schema using fh.build_[entity]_schema(default=current_data).
      • If Delete: Asks for confirmation, then calls coordinator.delete_[entity]_entity.

  4. Backup Management

    • Actions: Create Manual Backup, Delete Backup, Restore Backup.
    • Logic: Interfaces directly with storage_manager to handle JSON files.

4. Managed Entities & Configuration Details

Below are the specific fields managed by flow_helpers for each entity type. These schemas are identical in both Config and Options flows.

A. Kids

  • Name: Display name.
  • HA User: Link to a specific Home Assistant user (for authorization).
  • Notifications: Mobile Notify Service selection.
  • Language: Dashboard language preference.
  • Due Date Reminders: Toggle for 30-min warnings.

B. Parents

  • Name: Display name.
  • HA User: Link to Home Assistant user (Authorization level: Parent).
  • Associated Kids: Which kids this parent manages/receives notifications for.
  • Shadow Profile:
    • Allow Chores Assigned to Me: Creates a "Shadow Kid" entity so parents can have chores.
    • Enable Workflow: Adds Claim/Disapprove buttons for the parent.
    • Enable Gamification: Enables points/badges for the parent.

C. Chores (Complex Entity)

  • Basics: Name, Description, Icon, Labels, Points.
  • Assignment: Assigned Kids (Multi-select).
  • Logic:
    • Completion Criteria: Independent (Per-kid), Shared (All must do it), Shared First (Race to finish).
    • Approval Reset: At Midnight (Once/Multi), At Due Date (Once/Multi), Upon Completion.
    • Overdue Handling: Mark overdue, ignore, or reset.
    • Auto-Approve: Skip parent approval step.
  • Schedule:
    • Frequency: Daily, Weekly, Monthly, Custom, etc.
    • Daily Multi: Special mode for chores done multiple times a day (requires times 08:00|14:00).
    • Due Date: Specific date/time.
  • Per-Kid Overrides (Independent Mode): Due dates, applicable days, and times can be customized per kid.

D. Badges (Gamification)

  • Type: Cumulative (Lifetime points), Daily, Periodic, Achievement-Linked, Challenge-Linked, Special Occasion.
  • Target: Threshold (Points or Chore Count) required to earn.
  • Awards: What happens when earned? (Grant Points, Reward, Bonus, or Point Multiplier).
  • Maintenance:
    • Frequency: How often it resets (e.g., Weekly).
    • Rules: Points required to keep the badge.
    • Grace Period: Days allowed to recover before losing the badge.

E. Rewards

  • Basics: Name, Description, Icon, Labels.
  • Cost: Point cost to redeem.

F. Penalties & Bonuses

  • Basics: Name, Description, Icon, Labels.
  • Value: Point value (Penalties are stored as negative internally, displayed positive).

G. Achievements & Challenges

  • Achievements: Track streaks or totals.
    • Type: Chore Streak, Chore Total, Daily Minimum.
    • Target: Count required.
  • Challenges: Time-boxed goals.
    • Dates: Start Date, End Date.
    • Type: Total within window, Daily minimum.

H. General / System Options

  • Points Adjust Values: The buttons shown to parents (e.g., +1|-1|+5).
  • Update Interval: Coordinator polling frequency (default 5 min).
  • Calendar Period: How many days into the future to forecast (default 90).
  • Retention: How long to keep history (Daily/Weekly/Monthly/Yearly settings).
  • Legacy Entities: Toggle to show/hide old sensor entities (cleanup).
  • Backups: Max backups to retain.