--- id: CON-PFM-NOT-003 name: Staff Notification feature: FEAT-PFM-NOT-03 product_area: platform module: notifications revision: 1 status: draft product_intent: confirmed implementation_evidence: partially-observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- The product announcement model for staff: registered event declarations, committed submissions, recipient inbox items, channel outcomes and personal organization of those items. owned_by: MOD-PFM-NOT synonyms: - notice - in-app notification - inbox item not_to_be_confused_with: - 'An attention item, which is a condition someone must resolve' - 'A notification request, which is the producer’s announcement' facets: - name: Rendered item meaning: >- Recipient-specific title, body, subject record, destination, category, severity and occurrence time form the inbox item. used_for: Present the event and its destination to the recipient. - name: Personal organization meaning: >- Read state retains the first read instant; archive state controls ordinary inbox visibility. used_for: Drive personal views and unread totals. - name: Delivery progress meaning: >- Aggregate status distinguishes routed, delivering, delivered, partial delivery, failure, no channel and superseded items. used_for: Separate routing results from personal read state. - name: Combined contributions meaning: >- A collapsed item tracks the contribution count and latest fifty request references. used_for: Represent repeated activity without multiplying inbox rows. - name: Selection explanation meaning: >- Audience reasons and chosen or skipped channels explain why the item exists. used_for: Support the personal explanation sheet and administrator investigation. - name: Channel attempt history meaning: >- Selected-channel delivery records retain lifecycle, attempts and provider feedback. used_for: Trace what happened on each delivery route. - name: Future recipient configuration meaning: >- Stored preferences, quiet hours, digest timing, pauses and channel identities are not active delivery controls yet. used_for: Prepare persistence for future channel choice. - name: History window meaning: Monthly notice partitions maintain thirteen months of retained history. used_for: Bound retained activity while supporting year-spanning review. - name: Application identity meaning: >- A permanent three-segment key identifies the notification type and the application that declares it. used_for: Separate application namespaces and preserve references across releases. - name: Preference category meaning: >- Nine recognized categories organize notification types, including assignments, approvals, jobs, billing, security and system. used_for: >- Group personal choices without changing the category of an established key. - name: Importance meaning: 'Info, important and critical express the notice''s severity.' used_for: Present urgency and support future quiet-hour decisions. - name: Configuration boundary meaning: >- Fully configurable, channel-configurable and mandatory modes constrain future choices. used_for: >- Preserve required defaults, including e-mail when that channel is supported. - name: Supported delivery routes meaning: >- A declaration identifies supported and default channels and always includes console support. used_for: Limit routing and explain channels that are unavailable or unsupported. - name: Permitted audiences meaning: >- Types cover individual users, user groups, responsibilities, roles and permissions; system declarations can address HQ. used_for: Validate the producer's method of selecting recipients. - name: Declared request fields meaning: A closed data schema accompanies one to ten representative examples. used_for: Check submitted data and exercise wording during registration. - name: Localized content meaning: >- Each channel has language-specific templates, with English as the baseline. used_for: Render content for the recipient's locale. - name: Navigation and actions meaning: Destination metadata describes the console route and additional actions. used_for: Connect the notice to the work that prompted it. - name: Repetition and lifetime meaning: >- Collapse, expiry and replacement settings control how an event stays useful. used_for: Reduce bursts and stop stale work. - name: Registration lifecycle meaning: >- Declared types are active; omitted types become retired and remain retained. used_for: Preserve history while targeting unsettled requests for cancellation. - name: Stored workspace customization meaning: >- Settings and published wording overrides exist in persistence but are not applied by the current pipeline. used_for: Provide configuration primitives for a later planned release. - name: Operational channel mapping meaning: Code maps system definitions to Rhythm's Slack channel keys. used_for: Route HQ alerts without customer configuration. - name: Event identity meaning: >- A producer-selected event key derives the request identifier and recognizes repeated submissions. used_for: Make transaction retries refer to the existing request. - name: Recipient selection meaning: >- Entries specify users, scoped responsibilities, roles or permissions, with optional reasons, exclusions and actor inclusion. used_for: Resolve current staff recipients during processing. - name: Event context meaning: >- Declared data, a subject record and optional responsibility scope accompany the announcement. used_for: 'Support rendering, navigation and collapse matching.' - name: Delivery interval meaning: >- Optional not-before and expiry instants bound when the request remains useful. used_for: Delay future work and reject stale delivery. - name: Replacement and withdrawal meaning: >- A replacement key links successor events; cancellation withdraws an earlier request. used_for: Keep notices aligned with the underlying event. - name: Processing result meaning: >- Acceptance, empty audiences, invalidity, replacement, expiry and cancellation explain how processing ended. used_for: Include unsuccessful and recipient-less submissions in history. - name: Rejected outsiders meaning: >- Processing records named users removed by the customer and account boundary. used_for: Explain isolation decisions rather than silently losing recipients. - name: Closure meaning: >- Settlement follows expiry and completion of outstanding work, closing further request changes. used_for: Retain cancellation opportunities while the request remains open. - name: Transactional queue entry meaning: >- The producer inserts short-lived publication work in its business transaction. used_for: Tie dispatch availability to business commit. - name: HQ selection meaning: Only the reserved system workspace can address the system audience. used_for: >- Select Slack channels for operational alerts without selecting customer staff. relationships: - to: CON-PFM-NOT-004 statement: >- Registered notification wording belongs to the product; association e-mail templates belong to workflow authors. provenance: documented source: >- services-platform:docs/communications/architecture.md#22. Staff notifications: designed in the Platform Notifications architecture (2026-10-21) - to: CON-PFM-NOT-005 statement: >- Staff notifications and association communications share queued publication but have different recipient and content models. provenance: documented source: >- services-platform:docs/notifications.md#2. The producer’s door: the queue row lifecycle: - state: unread meaning: 'An unseen, applicable and unarchived item contributes to unread totals.' how_it_changes: Processing creates the item or its recipient marks it unread. - state: read meaning: 'The recipient has marked the item seen, removing it from unread totals.' how_it_changes: Opening or marking read records personal read state. - state: archived meaning: The recipient has removed the item from ordinary inbox views. how_it_changes: 'Archiving hides it, and restoration makes it visible again.' - state: no longer applies meaning: >- Historical content remains readable but is inapplicable and excluded from unread totals. how_it_changes: 'Withdrawal, replacement or eligible expiry supersedes it.' acted_on_by: - CAP-PFM-NOT-004 - CAP-PFM-NOT-005 - CAP-PFM-NOT-006 - CAP-PFM-NOT-007 - CAP-PFM-NOT-008 - CAP-PFM-NOT-009 - CAP-PFM-NOT-010 - CAP-PFM-NOT-011 - CAP-PFM-NOT-012 - CAP-PFM-NOT-014 - CAP-PFM-NOT-015 - CAP-PFM-NOT-001 - CAP-PFM-NOT-013 - CAP-PFM-NOT-002 - CAP-PFM-NOT-003 visible_to: - ACT-PFM-027 - ACT-PFM-028 - ACT-PFM-029 - ACT-PFM-030 - ACT-PFM-031 evidence: - >- Pinned evidence inventory 1: services-platform:modules/notifications/tests/integration/services/orchestration/cancel-and-supersede.integration.spec.js; services-platform:docs/milestones/plans/PLAT-M23-plan.humanized.md - >- Pinned evidence inventory 2: services-platform:modules/notifications/tests/integration/services/persistence/preferences.integration.spec.js - >- Pinned evidence inventory 1: services-platform:modules/notifications/tests/integration/services/orchestration/orchestrate-request.integration.spec.js; services-platform:modules/notifications/tests/unit/render-message.spec.js; services-platform:docs/communications/architecture.md; services-platform:docs/milestones/plans/PLAT-M23-plan.humanized.md - >- Pinned evidence inventory 1: services-platform:modules/notifications/tests/unit/audience-planner.spec.js; services-platform:docs/notifications.md - >- Pinned evidence inventory 2: services-platform:modules/notifications/tests/integration/services/orchestration/orchestrate-request.integration.spec.js; services-platform:docs/milestones/plans/PLAT-M23-plan.humanized.md supersedes: - CON-PFM-NOT-001 - CON-PFM-NOT-002 intent_sources: - 'services-platform:docs/milestones/plans/PLAT-M23-plan.humanized.md#2. Scope' --- # Staff Notification ## What It Is A staff notification connects an application event to the people whose work it concerns. It includes the declared event contract, the producer's submission and the recipient items created by processing. Staff experience it through their inbox; producers experience it as transactional publication; administrators inspect its request and delivery history. These are facets of one broad announcement model. The declaration separates stable product wording and validation from a particular event. The submission supplies the happening and audience. The recipient item provides localized content, a destination and personal read or archive state. Keeping those distinctions inside one concept prevents a route, queue record or classification from becoming a separate product noun. ## What It Is Not A notice does not grant the recipient responsibility or permission. Following its destination still uses the application's ordinary authorization. Staff notification also differs from association e-mail: the product declares notification wording and selects staff audiences, while association communications use workflow purposes and association or caller content. ## How It Is Used Application teams register event declarations during deployment. Producers publish within business transactions, and Platform resolves current audiences after commit. Rendering creates recipient items and available channel deliveries. Staff read and organize their own items; administrators inspect workspace outcomes and authorized HQ operators investigate customer history with grants. Repeated events can collapse, while withdrawal and expiry stop stale pending work. Already-delivered console items remain readable when they become inapplicable. Stored preferences are preparation rather than current channel behavior. Retirement cancellation and external provider proof have explicit limits in the findings. ## Its Facets **Rendered item.** Rendered content connects a recipient to the event and its work. **Personal organization.** Read and archive marks organize the recipient's own inbox. **Delivery progress.** Channel results determine progress independently of read state. **Combined contributions.** Matching events contribute to one item without losing request references. **Selection explanation.** Recipient selection and channel reasons make delivery understandable. **Channel attempt history.** Attempts and feedback preserve each channel's delivery history. **Future recipient configuration.** Stored choices prepare future controls without affecting current routing. **History window.** Monthly partitions bound the retained notification history. **Application identity.** Stable application keys identify declared event types across releases. **Preference category.** Categories group future preference choices while retaining declaration identity. **Importance.** Severity communicates how prominent an item should appear. **Configuration boundary.** Preference mode constrains permitted future channel choices. **Supported delivery routes.** Supported and default routes bound the delivery options. **Permitted audiences.** Accepted audience forms constrain how a producer selects people. **Declared request fields.** Closed data contracts and examples validate requests and templates. **Localized content.** Localized templates supply product-authored wording for each channel. **Navigation and actions.** Destination metadata connects notices to console work. **Repetition and lifetime.** Collapse, expiry and replacement bound useful event presentation. **Registration lifecycle.** Retirement preserves declaration identity and targets pending cancellation. **Stored workspace customization.** Stored workspace overrides await a future release plan. **Operational channel mapping.** System declarations map directly to Rhythm operational channel keys. **Event identity.** Producer event keys identify retried publication work. **Recipient selection.** Audience entries select current holders and eligible staff during processing. **Event context.** Event data and subject records support rendering and collapse. **Delivery interval.** Not-before and expiry instants govern pending work. **Replacement and withdrawal.** Replacement keys and cancellation keep announcements aligned with business state. **Processing result.** Processing outcomes explain acceptance and recipient-less requests. **Rejected outsiders.** Isolation refusals identify candidates excluded by customer boundaries. **Closure.** Settlement closes changes after expiry and outstanding work. **Transactional queue entry.** Transactional queue insertion follows the producer's commit or rollback. **HQ selection.** System audiences select HQ channels rather than customer staff. ## How It Relates Association communication shares durable queued publication but serves a different recipient and content outcome. Published association templates belong to that e-mail workflow. Responsibility assignments and customer provisioning are source events owned elsewhere; this module describes their notification contract without taking ownership of those business records. ## What It Could Become The product should complete the shared header bell and delivery explanations before relying on them as finished entry points. Later channel choices, quiet hours and digests require approved plans and runtime activation. Andrew should resolve the reserved system workspace and partial retirement recovery before design assumes those boundaries are settled.