govoplan-notifications/docs/INTERFACE_PATTERN_MIGRATION.md

Notifications interface pattern migration

Notifications uses the platform inbox/list-detail pattern for recipient work and the governed-operation pattern for delivery.

Surfaces

• notifications.route.notifications remains the route identifier so existing Views keep working.
• notifications.page.inbox owns status filtering and notification selection.
• notifications.page.detail owns message, source, recipient, and read/acknowledgement state.
• notifications.page.delivery owns sanitized delivery-attempt evidence.
• notifications.action.mark-read, notifications.action.acknowledge, and notifications.action.cancel describe recipient actions on the selected record.
• notifications.action.dispatch describes the privileged bounded delivery operation.
• notifications.settings.preferences and notifications.widget.summary remain composed Settings and Dashboard surfaces.

The backend and WebUI manifests publish the same identifiers and hierarchy. Notifications does not introduce a navigation entry because the title-bar bell is the platform entry point.

Consequences and recovery

Read and acknowledgement actions record durable recipient state. Cancellation is confirmed and is available only before an outcome becomes provider-accepted or otherwise terminal; it stops eligible local work and is not presented as remote recall. Dispatch is confirmed separately and processes at most 50 eligible tenant notifications per request. Accepted outcomes are not retried blindly.

Unavailable actions remain visible with explicit selection, permission, busy, terminal-state, and optional-Mail explanations. Personal preference drafts use the shared unsaved-change guard. The settings surface explains that in-product notifications continue when Mail is absent and that production email depends on the optional Mail capability.

Contextual help resolves through govoplan-docs when installed and through the hosted fallback otherwise. Delivery evidence remains sanitized and never exposes provider credentials or private sibling-module state.

Optional boundaries

Producing modules continue to own notification meaning. Notifications owns durable recipient and delivery state and calls optional Mail, Portal, Tasks, Calendar, Scheduling, and Workflow Engine integrations only through declared capabilities and references.