Notification System Architecture

Scope

The notification system defines an OS-native notification object model and UI primitive layer for Prox OS apps. @prox-os/notifications owns notification objects, preference primitives, presentation UI, mock data, and adapter examples.

Delivery, persistence, browser push permission, realtime subscription, Service Worker registration, email, SMS, webhooks, activity timelines, security policy, and OS routing remain outside this package.

Position

Notifications own event presentation objects and UI primitives.
Apps own domain meaning.
Runtime and backend layers own delivery, persistence, subscription, and policy.

This makes notifications reusable across OS shell surfaces, apps, resources, collaboration, AI runs, workspace events, security events, files, billing, and developer tooling without turning the package into a backend service.

Notification Versus Activity

Notifications answer "what needs attention now?" Activity answers "what happened over time?"

@prox-os/notifications should stay focused on attention, preference, action, badge, toast, inbox, and digest primitives. A future @prox-os/activity package can consume notification events, collaboration events, and domain events to build a durable timeline.

Runtime-Agnostic Delivery Boundary

Phase 1 ships components and mock data. It does not bind to a provider.

Future provider adapters can implement a narrow interface:

listNotifications(scope)
markRead(notification)
archive(notification)
dismiss(notification)
snooze(notification, until)
listPreferences(scope)
updatePreferences(rule)
subscribe(scope, callback)

Provider candidates remain future choices:

• local storage provider for development and personal preferences;
• backend notification API;
• Web Push and Service Worker;
• Cloudflare Queues and Durable Objects for routing;
• email digest and webhook delivery;
• per-workspace notification routing.

No provider is installed in Phase 1.

Event Flow

flowchart LR
  Domain["Domain event"] --> Draft["Notification draft"]
  Draft --> Object["OsNotification"]
  Object --> UI["Notification UI"]
  UI --> Intent["Action intent"]
  Intent --> Runtime["App or OS runtime"]
  Runtime --> Backend["Future backend/provider"]
  Backend --> Activity["Future activity/search/audit"]

The UI emits notification events and optional action intents. The app/runtime decides what to execute, which provider to call, and which permission or audit rules apply.

Action Boundary

The package consumes @prox-os/actions for action intent helpers:

• open notification target in OS;
• open target in new tab;
• mark notification read;
• archive notification;
• retry failed sync.

It does not execute the action. The Shell, app runtime, backend API, permission layer, and audit layer decide whether an action can run and what side effects it has.

Collaboration Boundary

Collaboration objects remain in @prox-os/collaboration. This package only maps collaboration events into notification drafts:

• mention selected or mentioned current user;
• comment created or updated;
• review requested;
• review approved or rejected;
• thread resolved or reopened.

The notification object links to the collaboration target, but it does not own the thread, comment, review, share state, or approval workflow.

Relationship To Future Packages

These packages should consume notification objects instead of redefining priority, status, source, target, digest, or preference contracts from scratch.

Data Model Sketch

classDiagram
  class OsNotification {
    id
    kind
    priority
    status
    tone
    title
    createdAt
  }
  class OsNotificationSource {
    id
    kind
    label
    appId
    workspaceId
  }
  class OsNotificationActor {
    id
    kind
    name
    handle
  }
  class OsNotificationTarget {
    id
    kind
    title
    route
    href
  }
  class OsNotificationActionRef {
    id
    label
    actionId
    href
  }
  class OsNotificationDigest {
    period
    unreadCount
    generatedAt
  }
  class OsNotificationPreferences {
    defaultChannels
    digestEnabled
    quietHoursEnabled
  }

  OsNotification --> OsNotificationSource
  OsNotification --> OsNotificationActor
  OsNotification --> OsNotificationTarget
  OsNotification --> OsNotificationActionRef
  OsNotificationDigest --> OsNotification
  OsNotificationPreferences --> OsNotification

Preference And Privacy Considerations

• Notifications can reveal sensitive work context. Production providers need workspace policy, permission checks, and preference enforcement.
• Security, billing, and AI approval notifications should not be muted or downgraded casually without explicit product policy.
• Browser push permission should be requested only by OS runtime UX, not by a primitive package.
• Email digest and webhook delivery require backend-side opt-in, unsubscribe, audit, and rate-limit policy.
• Public-link and permission-change notifications should route to security and audit surfaces once those packages exist.

Why Phase 1 Avoids Browser Push

Push notifications touch browser permission UX, Service Workers, backend delivery, identity, workspace routing, rate limits, quiet hours, audit, and privacy. Phase 1 keeps the package testable by shipping the object model, UI surface, mock data, and adapter seams first.

Phase Roadmap

Phase 1: Notification Contracts And Primitives

• Types.
• Helpers.
• Mock data.
• React primitives.
• Storybook examples.
• Action, collaboration, system, AI, security, and workspace adapters.
• Docs.

Phase 2: Local State And Provider Boundary

• OsNotificationProvider interface.
• Mock provider.
• Local storage provider.
• Preference persistence adapter.
• Optimistic mark-read, archive, dismiss, and snooze flows.

Phase 3: OS Runtime Integration

• Top bar notification bell.
• OS notification center.
• App, window, resource, and workspace scopes.
• Command palette integration.
• Search, activity, security, workspace, and AI integration.

Phase 4: Delivery Infrastructure

• Backend notification API.
• Cloudflare Queue or Durable Object routing.
• Web Push and Service Worker.
• Email digest.
• Webhook delivery.
• Per-workspace routing and quiet-hour policy.

Non-Goals

• No real push service.
• No Service Worker in Phase 1.
• No browser permission request.
• No email, SMS, or webhook delivery.
• No backend queue or retry system.
• No global OS daemon.
• No activity timeline.
• No security dashboard.
• No workspace management.
• No OS Shell private imports.