# ADR-0041: OSHUN Studio Observability and Operational Dashboards

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

## Context and Problem Statement

Studio has canonical metrics instrumentation, but operators still need a
first-class operational dashboard surface to detect regressions, triage policy
issues, and coordinate incident response across domains.

Without a unified observability dashboard architecture, OSHUN risks:

- fragmented dashboards with inconsistent SLI/SLO semantics
- weak incident triage due to missing drill-down context
- delayed detection of policy-denial or telemetry-quality regressions
- governance gaps between runtime operations and audit evidence

## Decision Drivers

- **Operator velocity**: fast, low-friction triage and remediation workflows.
- **Deterministic telemetry**: one SLI/SLO vocabulary across Studio surfaces.
- **Actionability**: every dashboard signal maps to a concrete workflow action.
- **Governance alignment**: incident, policy, and release evidence must align.
- **Scale**: dashboard design must span Yemaya/Isis/Hathor/Aja/Bellona.

## Considered Options

### Option 1: Per-Domain Operational Dashboards

Each domain publishes and manages its own dashboard patterns.

**Pros**:

- Local ownership and domain-specific optimization.

**Cons**:

- Inconsistent incident semantics and fragmented response workflows.
- Cross-domain rollups become costly and unreliable.

### Option 2: External Ops Tools Only

Use external observability tools with minimal Studio-native dashboard UI.

**Pros**:

- Lower Studio UI implementation effort.

**Cons**:

- Weak integration with Studio context, permissions, and workflow controls.
- Poor ergonomics for product/program operators working inside Studio.

### Option 3: Canonical Studio Observability Dashboard Surface (Chosen)

Implement a Studio-native operational dashboard with typed SLI/SLO cards, alert
streams, dependency health drill-downs, and policy-aware remediation actions.

**Pros**:

- Deterministic operational semantics across all Studio domains.
- Faster incident triage with direct linkage to recovery workflows.
- Strong alignment between telemetry, alerting, policy, and governance.

**Cons**:

- Requires coordinated schema/version governance across data producers.

## Decision Outcome

**Chosen option**: Option 3.

Observability and dashboard requirements:

1. **Canonical dashboard data contract** for SLI, SLO, and alert cards.
2. **Domain and workflow drill-down contract** for rapid causality isolation.
3. **Policy and permission contract** for remediation actions in-dashboard.
4. **Alert-state lifecycle contract** for ack, assign, resolve, and export.
5. **Operational readiness contract** for release and incident gating.

## Normative Rules

### Dashboard Data Contract

- Every dashboard card must include `signalId`, `signalType`, `status`,
  `window`, `currentValue`, `targetValue`, and `updatedAt`.
- Cards must map to one canonical source-of-truth telemetry stream.
- Stale data beyond the configured freshness window is release-blocking.

### SLI/SLO Contract

- Required SLI/SLO set includes success rate, latency, denial rate,
  availability, and telemetry completeness.
- SLO breach thresholds must be explicit and environment-aware.
- SLO calculations must be deterministic and reproducible.

### Drill-Down Contract

- Every alerting card must provide domain + workflow + dependency drill-down.
- Drill-down payload must preserve actor/workspace/release attribution.
- Drill-down actions must never bypass policy constraints.

### Policy and Permission Contract

- Dashboard remediation actions require role + permission-tier validation.
- Production-impacting actions require CAB approval evidence where applicable.
- Policy denials must be auditable and visible in dashboard history.

### Alert Lifecycle Contract

- Alerts must support `new`, `acknowledged`, `investigating`, `resolved`,
  `closed` states with deterministic transitions.
- Every transition must emit telemetry and audit events.
- Duplicate/looping transitions must be idempotent and traceable.

### Operational Readiness Contract

An observability dashboard release is valid only when all are true:

- SLI/SLO cards pass data-freshness and schema validation
- alert lifecycle actions pass role/policy checks
- drill-down links resolve to valid Studio context
- telemetry and audit emissions pass completeness checks
- runbook ownership/escalation artifacts are current

## Architecture Implications

- Web and BFF layers share one typed dashboard contract.
- Dashboard cards are sourced from canonical metrics instrumentation streams.
- Policy enforcement is reused from Studio RBAC and permission-tier systems.
- Incident playbooks become directly actionable from dashboard UI.

## Acceptance Criteria (OST-00225)

`OST-00225` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines dashboard data, SLI/SLO, drill-down, policy/permission,
   alert-lifecycle, and operational-readiness contracts.
4. ADR aligns with `ADR-0007` through `ADR-0040`, especially `ADR-0012`,
   `ADR-0039`, and `ADR-0040`.
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 operator response with dashboard-native triage/remediation context.
- Higher observability consistency and incident-detection reliability.
- Better governance posture for operational decisions and release gating.

### Negative

- Added implementation and maintenance overhead for typed dashboard contracts.
- Requires tight cross-team discipline for signal taxonomy and thresholds.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0045-oshun-studio-resilience-and-error-ux.md`
- `docs/adr/ADR-0046-oshun-studio-metrics-and-analytics-instrumentation.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`