homeio

Purpose

Notifications persist user-visible events in PostgreSQL and stream real-time updates to the UI with SSE. App operations, scheduled task failures, disk warnings, and other system events can create notifications.

Locations

• Server-side: lib/server/modules/notifications/
• Client-side: modules/system/components/notifications-panel.tsx, status-bar notification components, modules/system/hooks/useNotifications.ts
• Routes: app/api/v1/notifications/

Key Files

File	Role
lib/server/modules/notifications/service.ts	List/create/read/clear notifications
lib/server/modules/notifications/emitter.ts	In-memory SSE pub/sub
app/api/v1/notifications/stream/route.ts	Notification SSE endpoint
modules/system/hooks/useNotifications.ts	Client fetching and actions
modules/system/components/notifications-panel.tsx	Notifications UI

Public API

• listNotifications()
• createNotification()
• markAllNotificationsRead()
• clearAllNotifications()
• subscribeToNotifications()
• emitNotification(), emitNotificationReadAll(), emitNotificationCleared()

Contracts

• lib/shared/contracts/notifications.ts

Database Tables

• notifications

API Routes Owned

• GET /api/v1/notifications
• DELETE /api/v1/notifications
• POST /api/v1/notifications/read-all
• GET /api/v1/notifications/stream

Known Issues

• SSE pub/sub is in-memory and does not replay events after restart.
• The notification list has a hard cap in service code.
• Notification routes and stream are protected by requireApiSession().
• toRecord() in service.ts casts DB kind values without runtime validation, per the audit.

How To Extend

To add a new notification producer:

1. Import createNotification() in server-side code only.
2. Use an existing NotificationKind from lib/shared/contracts/notifications.ts or add one there.
3. Add tests for the producer path.
4. If the UI needs filtering/preferences, update modules/settings/components/panel/sections/notifications-section.tsx and related settings contracts.