Disciplines · Decisions (ADRs)

ADR-0030: OSHUN Studio Notification Center

Studio workflows generate high volumes of system, policy, review, and incident signals.

Accepted · 2026-02-23
10sections3 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN Security
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio workflows generate high volumes of system, policy, review, and incident signals. Existing notification patterns are distributed across surfaces and do not provide one authoritative center for triage, prioritization, and action.

Without a first-class Studio notification center, OSHUN risks:

  • missed high-priority governance alerts
  • inconsistent triage and acknowledgement workflows
  • duplicate/fragmented notification handling across domains
  • weak auditability of notification response actions

Decision Drivers#

  • Operational responsiveness: faster triage and action on critical alerts.
  • Consistency: unified notification model across Studio domains.
  • Signal quality: deduplicated, prioritized, actionable notification feed.
  • Traceability: auditable acknowledgement and response actions.
  • Interoperability: align with Yemaya/Isis/Hathor/Aja/Bellona + Project Obsidian.

Considered Options#

Option 1: Keep Notifications Embedded in Each Surface#

Continue handling notification cues in individual Studio pages only.

Pros:

  • Minimal near-term implementation effort.

Cons:

  • Fragmented signal handling and higher miss risk.
  • No unified triage workflow.

Option 2: Basic Unified Feed Without Workflow Semantics#

Aggregate notifications in one list but without priorities/escalation states.

Pros:

  • Better visibility than fragmented model.

Cons:

  • Limited actionability for governance-critical signals.
  • Weak workflow and compliance traceability.

Option 3: Unified Notification Center with Priority + Action Contracts (Chosen)#

Adopt one Studio notification center contract with canonical payloads, prioritization, deduplication, acknowledgement semantics, and escalation flows.

Pros:

  • Deterministic triage and response behavior.
  • Better incident and governance responsiveness.
  • Stronger audit/compliance traceability for notification handling.

Cons:

  • Additional schema/governance complexity.

Decision Outcome#

Chosen option: Option 3.

Notification center requirements:

  1. Notification payload contract for canonical actor/source/severity/context.
  2. Priority and deduplication contract for ordering and signal collapse.
  3. Action workflow contract for acknowledge, assign, resolve, escalate.
  4. Compatibility contract for schema/version and routing evolution.
  5. Release governance with validation, approval, telemetry/audit, and rollback.

Normative Rules#

Notification Payload Contract#

  • Notifications must include stable id, source, severity, summary, and context.
  • Every actionable notification must link to target workflow context.
  • Invalid payloads must be rejected from production feed rendering.

Priority and Deduplication Contract#

  • Notifications must use deterministic severity/priority classification.
  • Duplicate signals for same incident context must collapse with counters.
  • Critical notifications must surface above lower-severity items.

Action Workflow Contract#

  • Notification actions must support acknowledge, assign, resolve, and escalate.
  • Action state transitions must be deterministic and auditable.
  • Unresolved critical notifications must trigger escalation workflows.

Compatibility Contract#

  • Payload schema changes require compatibility checks.
  • Breaking changes require migration guidance and rollback references.
  • Domain routing metadata must remain backward compatible.

Release Validity Contract#

A notification-center release is valid only when all are true:

  • payload validation checks pass
  • priority/deduplication behavior passes deterministic tests
  • action workflow transitions pass integrity checks
  • telemetry/audit records are complete
  • rollback strategy is documented

Architecture Implications#

  • Studio web surfaces expose centralized notification center workflows.
  • BFF orchestrates notification ingestion, deduplication, and state transitions.
  • Domain adapters emit canonical notification payloads into shared pipelines.
  • Analytics pipelines capture notification triage and response outcomes.

Acceptance Criteria (OST-00137)#

OST-00137 is complete only when:

  1. ADR exists at docs/adr/ADR-0036-oshun-studio-notification-center.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines notification payload, priority/deduplication, action workflow, compatibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0029, especially ADR-0012.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, libs/oshun/analytics, and libs/oshun/domain-registry.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Faster and more reliable response to governance-critical signals.
  • Consistent notification handling across all Studio domains.
  • Improved audit/compliance evidence for alert lifecycle handling.

Negative#

  • Increased schema and deduplication governance complexity.
  • Requires strict notification routing and payload quality controls.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0035-oshun-studio-audit-and-compliance-surfaces.md

References#

  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/design/ux-principles.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md