Notifications & Reminders

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/notifications/scheduler.ts
• src/lib/notifications/reminderContent.ts
• ios-shell/www/app.js
• CLAUDE.md
• GLOSSARY.md
• src/app/(app)/settings/app/page.tsx/settings/app/page.tsx)

Notifications & Reminders is the system responsible for alerting users about upcoming due dates for contracts, warranties, and vehicle obligations. It uses a threshold-based schedule to send messages across multiple delivery channels, including email, push notifications via ntfy, and outbound webhooks.

In the self-hosted environment, the system relies on a centralized scheduler (node-cron) to check for expirations. In the mobile standalone environment, it uses native device notifications. Sources: src/lib/notifications/scheduler.ts:1-10, ios-shell/www/app.js:632-640, CLAUDE.md:120-130

Architecture and Delivery Flow

The notification system follows a fan-out architecture. A central scheduler identifies records nearing a "Due" state based on a Due policy. It then generates content and delivers it to all configured channels.

The diagram shows the sequence from the initial trigger to final delivery across multiple channels. Sources: src/lib/notifications/scheduler.ts:40-100, CLAUDE.md:120-130

Key Delivery Channels

The system supports three primary outbound channels for self-hosted instances:

Channel	Implementation	Purpose
Email	SMTP	Sends formatted HTML and text reminders to household members.
Ntfy	HTTP Push	Delivers real-time push notifications via ntfy.sh or a self-hosted ntfy server.
Webhooks	HMAC-SHA256 Signed POST	Notifies external platforms like Home Assistant of upcoming due dates.

Sources: src/lib/notifications/scheduler.ts:1-10, src/app/(app)/settings/app/page.tsx:88-120, CLAUDE.md:120-130

Scheduled Checks and Logic

The runExpirationCheck function is the core execution block. It performs several cleanup tasks before processing reminders:

1. Purges expired items from the Trash.
2. Removes old sync receipts.
3. Reconciles the document store.
4. Identifies active contracts, products, and vehicles with defined expiry dates.

Sources: src/lib/notifications/scheduler.ts:20-40

Reminder Thresholds

Reminders are sent when a record crosses specific day thresholds before its end date. The default thresholds are 30, 14, 7, and 1 days. If multiple thresholds are crossed at once (e.g., when adding an already overdue record), the system sends exactly one catch-up reminder per channel to avoid flooding the user. Sources: src/lib/notifications/scheduler.ts:45-50, GLOSSARY.md:144-150

Content Generation

The reminderContent.ts module handles message formatting. It ensures that wording remains consistent across channels while respecting individual user date formats.

export function buildReminderEmail(input: ReminderInput): { subject: string; text: string; html: string } {
  // ... formats dates based on user preferences (e.g., DD/MM/YYYY)
  // ... constructs subject line: "Reminder: [Title] expires in [X] days"
  // ... appends appUrl for direct record linking
}

Sources: src/lib/notifications/reminderContent.ts:114-145

Mobile Standalone Reminders

In standalone mode, the application does not communicate with a server. Instead, it schedules notifications directly on the mobile device using the @capacitor-community/sqlite and LocalNotifications plugins.

Standalone Sync Process

1. You trigger the sync via the UI.
2. The app requests LocalNotifications permissions.
3. It creates a dedicated channel: hearth-standalone-reminders.
4. It calculates all future notification dates for current records and schedules them.

Configuration and Health

Reminders can be configured in the Settings → Household & System → System settings page. Administrators can set global defaults for thresholds and Cron schedules.

Delivery Health

Hearth provides a "Reminder delivery health" card. This surfaces:

• Delivery Ready: Whether at least one channel is configured.
• Uncovered Records: Records due within 90 days that lack working reminder coverage.
• Last Activity: The timestamp of the last successful or failed delivery.
• APP_URL Status: Warns if the server URL is missing, which prevents links in reminders from working.

Sources: src/components/HouseholdReminderHealthCard.tsx:16-50, src/components/ReminderHealthCard.tsx:28-50

Summary

The Notifications & Reminders system ensures the household stays informed of critical dates. It utilizes a robust scheduling logic that prevents redundant notifications and supports both self-hosted multi-channel fan-out and native mobile local scheduling. Success is tracked through integrated health monitoring that alerts admins to configuration gaps.