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

Technical: Notifications

This document provides technical details about the KidsChores notification system architecture for developers and advanced users.

Terminology: This document uses terms like "chore ID", "kid ID", and "entity ID". For precise definitions of Item vs Entity, Internal ID, and Domain Item terminology, see ARCHITECTURE.md - Lexicon Standards.

Notification Replacement System (Smart Tags)

Notifications use a smart tagging system to prevent notification spam. When a new notification is sent with the same tag, it replaces the previous notification instead of stacking.

How Tags Work

Each notification is tagged with a unique identifier combining the config entry ID, entity type, entity ID, and kid ID:

Multi-Instance Support: The config entry ID is included as the first identifier to ensure notifications from different KidsChores integrations don't interfere with each other. Each identifier is truncated to 8 characters to stay within mobile notification tag limits.

Notification Type	Tag Pattern	Example
Chore Approval	`kidschores-status-{entry_id}-{chore_id}-{kid_id}`	`kidschores-status-abc12345-def67890-ghi01234`
Reward Approval	`kidschores-rewards-{entry_id}-{reward_id}-{kid_id}`	`kidschores-rewards-abc12345-xyz78901-ghi01234`
Overdue Chores	`kidschores-overdue-{entry_id}-{chore_id}-{kid_id}`	`kidschores-overdue-abc12345-def67890-ghi01234`
Due Soon Chores	`kidschores-due_window-{entry_id}-{chore_id}-{kid_id}`	`kidschores-due_window-abc12345-def67890-ghi01234`
System Alerts	`kidschores-system-{entry_id}-{kid_id}`	`kidschores-system-abc12345-ghi01234`

Example: Multiple Chore Notifications

When Zoë claims multiple chores, each notification remains independent:

Zoë claims "Make Bed" (chore1) → Tag: kidschores-status-entry123-chore1ab-zoe12345
Zoë claims "Feed Dog" (chore2) → Tag: kidschores-status-entry123-chore2cd-zoe12345

Result: Parents see both notifications because each chore has a unique tag.

Reminder Notifications

When parents press "Remind in 30 min":

A new notification is scheduled with the same tag as the original chore
After 30 minutes, the reminder replaces only that specific chore's notification
Other chore notifications remain untouched

Automatic Notification Clearing

The integration automatically clears certain notifications from mobile devices to prevent stale action buttons and notification spam.

Approval/Disapproval Clearing (Multi-Parent Support):

When any parent approves or disapproves a chore/reward (via notification button OR dashboard), the integration sends a clear_notification message to all parent devices
This removes the original "Chore/Reward Claimed" notification with action buttons from all parents
Example: Kid claims chore → Both parents notified → Parent 1 approves via notification button → Notification cleared from both parent devices
Why: Prevents Parent 2 from seeing stale action buttons for already-processed claims

Claim/Approval Path (Due Soon notifications):

When a kid claims a "Chore Due Soon" notification, it's automatically replaced by "Chore Claimed" sent to parents
When a chore is approved, the "Chore Claimed" notification is cleared from all parent devices

Which Notifications Are Auto-Cleared:

✅ Chore Claimed - Cleared when any parent approves/disapproves (any path)
✅ Reward Claimed - Cleared when any parent approves/disapproves (any path)
✅ Chore Overdue (Kids) - Cleared when kid claims chore OR parent approves
✅ Chore Due Soon (Kids) - Cleared when kid claims chore OR parent approves
✅ Chore/Reward Reminder (30 min) - Cleared when any parent approves/disapproves
✅ Chore Disapproved - Auto-clears original parent claim notifications
❌ All other notifications - Remain until dismissed by user

Enhanced Auto-Clearing for Kids

The notification system now provides comprehensive auto-clearing for kid notifications:

Chore State Transitions:

When a kid claims an overdue chore → Overdue notification is cleared from their device
When a kid claims a due-soon chore → Due-soon notification is cleared from their device
When a parent approves any chore → Both overdue AND due-soon notifications cleared from kid's device
When a parent disapproves a chore → Kid receives disapproval notification, parent claim notifications are cleared

Why This Matters: Kids no longer see stale "Chore Overdue" or "Claim Now" notifications after they've taken action. This prevents confusion and duplicate claims.

Approval Aggregation (Chores Only)

When a kid has multiple pending chores waiting for approval, the integration uses smart aggregation to reduce notification clutter for parents:

How It Works:

Kid claims multiple chores → Each claim generates individual notifications to parents
Parent approves one chore → Old notification is cleared and replaced with an updated aggregated notification:
- Shows: "[Kid] has N pending chores. Latest: [Chore Name] (X points)"
- Includes: Action buttons for the most recent pending chore
Parent continues approving → Notification updates with new count and latest chore details
Last chore approved → No replacement notification sent (all approvals complete)

Rewards: Do not use aggregation. Each reward approval sends independent notifications and clears the original claim notification.

Why This Matters: Parents with multiple kids/chores see consolidated status updates instead of a growing list of individual notifications.

Translation System

Notifications are translated per-user using the integration's custom translation architecture:

14 languages supported via Crowdin (English, Spanish, Dutch, French, German, Italian, and more)
Per-user preferences - Kids and parents can use different languages
Automatic fallback to English for missing translations
Translation files: translations_custom/{lang}_notifications.json
Translation key pattern: {notification_type}_{audience} (e.g., chore_approved_kid, badge_earned_parent)

Notification Translation Flow

Integration determines recipient's language preference
Loads appropriate translation file (en_notifications.json, es_notifications.json, etc.)
Formats notification with dynamic placeholders ({kid_name}, {chore_name}, {points}, etc.)
Sends translated notification to user's mobile device

Key Features:

Titles, messages, and action button labels all translated
Emojis preserved across all languages
Placeholder replacement happens after translation

For complete translation architecture details (sensor entities, translation constants, Crowdin workflow), see ARCHITECTURE.md - Translation Architecture.

Implementation Reference

Notification-Specific Code

Notification Manager: managers/notification_manager.py - Core notification logic, smart tagging, auto-clearing, aggregation
Action Handler: notification_action_handler.py - Processes action button presses from mobile notifications
Translation Files: translations_custom/{lang}_notifications.json - Notification text for 14 languages

Notification Constants

All notification constants follow the TRANS_KEY_NOTIF_* pattern in const.py:

TRANS_KEY_NOTIF_TITLE_* - Translation keys for notification titles
TRANS_KEY_NOTIF_MESSAGE_* - Translation keys for notification messages
TRANS_KEY_NOTIF_ACTION_* - Translation keys for action button labels

Example Pattern:

TRANS_KEY_NOTIF_TITLE_CHORE_APPROVED_KID = "chore_approved_kid"
TRANS_KEY_NOTIF_MESSAGE_CHORE_APPROVED_KID = "chore_approved_kid"

For complete constant naming conventions and patterns, see DEVELOPMENT_STANDARDS.md - Constant Naming Standards.