Skip to content
This repository was archived by the owner on Mar 13, 2026. It is now read-only.

Technical: Notifications

Jump to bottom
ccpk1 edited this page Feb 11, 2026 · 1 revision

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:

  1. Zoë claims "Make Bed" (chore1) → Tag: kidschores-status-entry123-chore1ab-zoe12345
  2. 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:

  1. Kid claims multiple chores → Each claim generates individual notifications to parents
  2. 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
  3. Parent continues approving → Notification updates with new count and latest chore details
  4. 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

  1. Integration determines recipient's language preference
  2. Loads appropriate translation file (en_notifications.json, es_notifications.json, etc.)
  3. Formats notification with dynamic placeholders ({kid_name}, {chore_name}, {points}, etc.)
  4. 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.

See Also

Architecture & Design:

Development Standards:

Last Updated: February 2026 (v0.5.0)

📖 KidsChores Wiki

🚀 Getting Started

⚙️ Configuration

🔧 Services & Examples

📖 Advanced Topics

📚 Technical Reference

👩‍🔧 Troubleshooting

Clone this wiki locally