# D1: Dashboard Specification ## Universal Review Taxonomy (URT) v5.1 - Integration Track **Document**: D1 - Dashboard Specification **Version**: 1.0 **Status**: Production Ready **Date**: 2026-01-23 **Depends On**: B2-database-schema.sql, B3-owner-routing.md, C1-Issue-Lifecycle-Framework.md, C2-KPI-Mapping-Guide.md --- ## Purpose This specification defines the complete UI/visualization requirements for URT v5.1 dashboards. It provides: - Dashboard layouts for different user personas (Executive, Operations, Analyst) - Widget specifications with data sources and refresh rates - Color schemes aligned with URT taxonomy - Filter components and interaction patterns - ASCII wireframes for each view - API endpoint requirements and caching strategies - Role-based access control specifications --- ## Table of Contents 1. [Dashboard Architecture](#1-dashboard-architecture) 2. [Executive Dashboard](#2-executive-dashboard) 3. [Operations Dashboard](#3-operations-dashboard) 4. [Analytics Dashboard](#4-analytics-dashboard) 5. [Deep-Dive Views](#5-deep-dive-views) 6. [Widget Specifications](#6-widget-specifications) 7. [Color Schemes](#7-color-schemes) 8. [Filter Components](#8-filter-components) 9. [Data Requirements](#9-data-requirements) 10. [User Roles & Permissions](#10-user-roles--permissions) 11. [Responsive Design](#11-responsive-design) 12. [Implementation Notes](#12-implementation-notes) --- ## 1. Dashboard Architecture ### 1.1 System Overview ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ URT DASHBOARD ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ PRESENTATION LAYER │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │Executive │ │Operations│ │Analytics │ │Deep-Dive │ │ │ │ │ │Dashboard │ │Dashboard │ │Dashboard │ │ Views │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └───────┼─────────────┼─────────────┼─────────────┼────────────────────┘ │ │ │ │ │ │ │ │ ┌───────┴─────────────┴─────────────┴─────────────┴────────────────────┐ │ │ │ STATE MANAGEMENT │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │Filter State│ │ User Prefs │ │Cache Layer │ │Real-time │ │ │ │ │ │ Manager │ │ Storage │ │ (Redis) │ │WebSockets │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ │ └─────────────────────────────────┬────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────┴────────────────────────────────────┐ │ │ │ API LAYER │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ KPI │ │ Issue │ │ Span │ │ Alert │ │ │ │ │ │ Endpoints│ │ Endpoints│ │ Endpoints│ │ Endpoints│ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └───────┴─────────────┴─────────────┴─────────────┴────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────┴────────────────────────────────────┐ │ │ │ DATA LAYER (B2) │ │ │ │ ┌────────────────────┐ ┌────────────────────┐ │ │ │ │ │ Materialized Views │ │ Base Tables │ │ │ │ │ │ mv_domain_summary │ │ reviews, spans │ │ │ │ │ │ mv_category_break │ │ issues, causal │ │ │ │ │ │ mv_issue_pipeline │ │ state_history │ │ │ │ │ │ mv_cr_trends │ │ annotation_audit │ │ │ │ │ │ mv_daily_volume │ │ │ │ │ │ │ └────────────────────┘ └────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 1.2 Dashboard Personas | Dashboard | Primary User | Focus | Refresh Rate | |-----------|--------------|-------|--------------| | **Executive** | C-Suite, Directors | OEI, trends, alerts | 15 minutes | | **Operations** | Managers, Team Leads | Issues, SLAs, workload | 5 minutes | | **Analytics** | Analysts, Data Scientists | Time-series, anomalies | 15 minutes | | **Deep-Dive** | All users | Individual review/span detail | On-demand | ### 1.3 Technology Recommendations | Component | Recommended Library | Alternatives | |-----------|---------------------|--------------| | **Charting** | Recharts | D3.js, Chart.js, ECharts | | **Data Grid** | AG Grid | React Table, TanStack Table | | **Gauges** | Custom SVG / D3 | Recharts custom, ApexCharts | | **Radar Charts** | Recharts | Chart.js, Nivo | | **Sankey Diagrams** | D3-Sankey | Plotly, ECharts | | **State Management** | Zustand / Redux Toolkit | Jotai, Recoil | | **Real-time** | Socket.io | Pusher, Ably | --- ## 2. Executive Dashboard ### 2.1 Purpose & Key Metrics The Executive Dashboard provides at-a-glance visibility into overall customer experience health. It answers: "How are we doing, and where should I focus?" **Primary Metrics**: - Overall Experience Index (OEI) - 7-Domain Performance Radar - Critical Issue Alerts - Week-over-Week and Month-over-Month Trends ### 2.2 Wireframe ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ URT Dashboard [Executive v] Period: [Last 30 days v] [Filters] [Export] │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────┐ ┌─────────────────────────────────┐ │ │ │ OVERALL EXPERIENCE INDEX │ │ DOMAIN RADAR CHART │ │ │ │ │ │ │ │ │ │ ┌─────────────┐ │ │ O │ │ │ │ / \ │ │ /|\ │ │ │ │ / \ │ │ R / \ P │ │ │ │ │ 79.9 │ │ │ / . \ │ │ │ │ \ / │ │ V ───.───. J │ │ │ │ \ ▲ +2.3% / │ │ \ . / │ │ │ │ └─────────────┘ │ │ A \ / E │ │ │ │ │ │ \|/ │ │ │ │ Good [████████████░░] │ │ │ │ │ │ │ │ ── Current -- Prev Month │ │ │ └─────────────────────────────────────┘ └─────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ DOMAIN SCORE CARDS (7 CARDS) │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ │ │ O │ │ P │ │ J │ │ E │ │ A │ │ V │ │ R │ │ │ │ │ │ 82 │ │ 88 │ │ 75 │ │ 80 │ │ 85 │ │ 68 │ │ 78 │ │ │ │ │ │▲+3.2 │ │▲+1.8 │ │▼-0.5 │ │▲+2.1 │ │→+0.3 │ │▼-2.4 │ │→+0.8 │ │ │ │ │ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │~~~~~~│ │ │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │ │ │ CRITICAL ISSUES ALERT PANEL │ │ TREND INDICATORS │ │ │ │ │ │ │ │ │ │ [!] 5 Open I3 Issues > 24h │ │ IMPROVING ▲ │ │ │ │ └─ ISSUE-2026-0142 (O2.05) │ │ • O: Product Quality (+3.2) │ │ │ │ └─ ISSUE-2026-0156 (P1.02) │ │ • P: Personnel Index (+1.8) │ │ │ │ └─ ... │ │ • E: Environment (+2.1) │ │ │ │ │ │ │ │ │ │ [!] V Domain Below Target │ │ STABLE → │ │ │ │ └─ Score: 68 (Target: 70) │ │ • A: Accessibility (+0.3) │ │ │ │ │ │ • R: Relationship (+0.8) │ │ │ │ [!] CR-W Spike Detected │ │ │ │ │ │ └─ J1.01: Wait Time │ │ DECLINING ▼ │ │ │ │ │ │ • J: Process Efficiency (-0.5) │ │ │ │ [View All Alerts →] │ │ • V: Value Perception (-2.4) │ │ │ └───────────────────────────────────┘ └───────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ 12-WEEK OEI TREND LINE │ │ │ │ 85 ┤ │ │ │ │ 80 ┤ ___*───* │ │ │ │ 75 ┤ ___*───*───*───*─── │ │ │ │ 70 ┤ *───* │ │ │ │ 65 ┤ │ │ │ │ └────W1───W2───W3───W4───W5───W6───W7───W8───W9──W10──W11──W12── │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────┐ ┌───────────────────────────────────┐ │ │ │ COMPOSITE INDICES │ │ QUICK STATS │ │ │ │ │ │ │ │ │ │ Service Excellence (SEI) │ │ Reviews This Period: 2,847 │ │ │ │ [████████████████████░░░] 82.2 ▲ │ │ Spans Classified: 4,215 │ │ │ │ │ │ Open Issues: 23 │ │ │ │ Value Perception (VPI-C) │ │ SLA Compliance: 91.5% │ │ │ │ [████████████░░░░░░░░░░░] 61.9 ▼ │ │ Avg Resolution Time: 2.3 days │ │ │ │ │ │ Verification Rate: 68.4% │ │ │ │ Trust & Loyalty (TLI) │ │ │ │ │ │ [████████████████████░░░] 84.5 → │ │ Last Updated: 2 min ago │ │ │ └───────────────────────────────────┘ └───────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 2.3 Widget Specifications #### 2.3.1 OEI Gauge | Attribute | Specification | |-----------|---------------| | **Type** | Radial gauge / semi-circular dial | | **Data Source** | Computed from `mv_domain_summary` | | **Calculation** | Per C2: weighted sum of domain scores | | **Ranges** | 0-50 (Red), 50-65 (Yellow), 65-85 (Green), 85-100 (Blue) | | **Refresh** | 15 minutes | | **Interactions** | Click to drill into domain breakdown | | **Library** | Custom SVG or Recharts RadialBarChart | **SQL Query**: ```sql SELECT SUM(CASE domain_code WHEN 'O' THEN avg_score * 0.20 WHEN 'P' THEN avg_score * 0.18 WHEN 'J' THEN avg_score * 0.15 WHEN 'E' THEN avg_score * 0.12 WHEN 'A' THEN avg_score * 0.10 WHEN 'V' THEN avg_score * 0.12 WHEN 'R' THEN avg_score * 0.13 END) AS oei FROM mv_domain_summary; ``` #### 2.3.2 Domain Radar Chart | Attribute | Specification | |-----------|---------------| | **Type** | Radar / Spider chart | | **Data Source** | `mv_domain_summary` | | **Axes** | 7 axes (O, P, J, E, A, V, R) | | **Scale** | 0-100 per axis | | **Overlays** | Current period (solid), Previous period (dashed) | | **Colors** | Current: domain-specific, Previous: gray | | **Refresh** | 15 minutes | | **Interactions** | Hover for values, click axis to drill into domain | #### 2.3.3 Domain Score Cards | Attribute | Specification | |-----------|---------------| | **Type** | Metric card with sparkline | | **Count** | 7 cards (one per domain) | | **Layout** | Horizontal row, responsive wrap | | **Elements** | Domain code, score, delta, 12-week sparkline | | **Colors** | Header bar in domain color | | **Refresh** | 15 minutes | | **Interactions** | Click to navigate to Operations view filtered by domain | #### 2.3.4 Critical Issues Alert Panel | Attribute | Specification | |-----------|---------------| | **Type** | Alert list with severity icons | | **Data Source** | `issues` table filtered by state and priority | | **Max Items** | 5 (with "View All" link) | | **Alert Types** | I3 issues, threshold breaches, CR-W spikes, SLA violations | | **Refresh** | 5 minutes (more frequent than page) | | **Interactions** | Click issue ID to open Deep-Dive view | **Alert Query**: ```sql SELECT issue_id, primary_subcode, state, priority_score, EXTRACT(EPOCH FROM (NOW() - created_at)) / 3600 AS age_hours FROM issues WHERE state NOT IN ('VERIFIED', 'DECLINED') AND max_intensity = 'I3' AND deleted_at IS NULL ORDER BY priority_score DESC LIMIT 5; ``` #### 2.3.5 Trend Indicators Panel | Attribute | Specification | |-----------|---------------| | **Type** | Categorized list with arrows | | **Categories** | Improving (>+2%), Stable (-2% to +2%), Declining (<-2%) | | **Data Source** | Compare `mv_domain_summary` with previous period | | **Visual** | Green arrows up, gray arrows right, red arrows down | | **Refresh** | 15 minutes | --- ## 3. Operations Dashboard ### 3.1 Purpose & Key Metrics The Operations Dashboard provides real-time visibility into issue management and team workload. It answers: "What needs attention now, and who is handling it?" **Primary Metrics**: - Issue Pipeline by State - SLA Compliance Gauges - Owner Workload Distribution - Category Heatmap - Active Issue Table ### 3.2 Wireframe ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ URT Dashboard [Operations v] Domain: [All v] Team: [All v] [Filters] │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ISSUE PIPELINE (STATE FLOW) │ │ │ │ │ │ │ │ DETECTED → ACKNOWLEDGED → IN_PROGRESS → RESOLVED → VERIFIED │ │ │ │ │ │ │ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ │ │ 12 │───│ 8 │───│ 15 │───│ 7 │───│ 23 │ │ │ │ │ │ issues │ │ issues │ │ issues │ │ issues │ │ issues │ │ │ │ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │ │ │ Avg: 4h Avg: 2h Avg: 3d Pending Complete │ │ │ │ Verification │ │ │ │ │ │ │ │ Side tracks: [DECLINED: 5] [REOPENED: 3] [STALE: 2] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────┐ ┌─────────────────────────────────────┐ │ │ │ SLA COMPLIANCE GAUGES │ │ OWNER WORKLOAD DISTRIBUTION │ │ │ │ │ │ │ │ │ │ TTA (Time to Acknowledge) │ │ Team │ Open │ Load │Cap │ │ │ │ ┌────────────────────────┐ │ │ ───────────────────────────────── │ │ │ │ │████████████████░░░░│94.2%│ │ │ Operations │ 12 │████░│ 80%│ │ │ │ └────────────────────────┘ │ │ HR/Training │ 8 │███░░│ 60%│ │ │ │ Target: 95% ▼ -0.8% WoW │ │ Product │ 6 │██░░░│ 45%│ │ │ │ │ │ Engineering │ 5 │██░░░│ 40%│ │ │ │ TTR (Time to Resolve) │ │ Facilities │ 4 │█░░░░│ 30%│ │ │ │ ┌────────────────────────┐ │ │ Finance │ 3 │█░░░░│ 25%│ │ │ │ │██████████████░░░░░│87.5%│ │ │ CX Leadership │ 2 │░░░░░│ 15%│ │ │ │ └────────────────────────┘ │ │ │ │ │ │ Target: 90% ▼ -1.3% WoW │ │ [!] Operations at 80% capacity │ │ │ │ │ │ │ │ │ │ Recurrence Rate │ │ │ │ │ │ ┌────────────────────────┐ │ │ │ │ │ │ │███░░░░░░░░░░░░░░░│7.8% │ │ │ │ │ │ │ └────────────────────────┘ │ │ │ │ │ │ Target: <10% ▼ -1.2% WoW │ │ │ │ │ └─────────────────────────────────┘ └─────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ CATEGORY BREAKDOWN HEATMAP │ │ │ │ │ │ │ │ │ O │ P │ J │ E │ A │ V │ R │ │ │ │ │ ─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤ │ │ │ │ 1 │ ██ │ ███ │ ████│ █ │ █ │ ██ │ █░ │ ← Function/Attitude │ │ │ │ 2 │ ███ │ ██ │ ██ │ ██ │ █ │ ███ │ █░ │ ← Quality/Competence │ │ │ │ 3 │ █░ │ █░ │ ███ │ █ │ █ │ █░ │ ██ │ ← Complete/Response │ │ │ │ 4 │ ██ │ ██ │ ████│ ███ │ ██ │ ██ │ █░ │ ← Fit/Communication │ │ │ │ │ │ │ │ Legend: ░ Low (0-5) █ Medium (5-15) ██ High (15-30) ███ Critical │ │ │ │ Intensity indicates negative span count in period │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ACTIVE ISSUES TABLE │ │ │ │ │ │ │ │ [Search...________________________] [State: All v] [Priority: All v] │ │ │ │ │ │ │ │ ┌────────────┬─────────┬───────┬──────────┬───────┬───────┬──────────┐ │ │ │ │ │ Issue ID │ Subcode │ State │ Priority │ Age │ Spans │ Owner │ │ │ │ │ ├────────────┼─────────┼───────┼──────────┼───────┼───────┼──────────┤ │ │ │ │ │ISSUE-0142 │ O2.05 │ INP │ ████ 5.60│ 3d 4h │ 5 │ Kitchen │ │ │ │ │ │ISSUE-0156 │ P1.02 │ ACK │ ████ 4.20│ 1d 2h │ 3 │ HR │ │ │ │ │ │ISSUE-0161 │ J1.01 │ DET │ ███░ 3.85│ 4h │ 2 │ Ops │ │ │ │ │ │ISSUE-0167 │ E4.01 │ INP │ ███░ 3.50│ 8h │ 1 │ Safety │ │ │ │ │ │ISSUE-0172 │ V1.04 │ ACK │ ██░░ 2.90│ 12h │ 2 │ Finance │ │ │ │ │ └────────────┴─────────┴───────┴──────────┴───────┴───────┴──────────┘ │ │ │ │ │ │ │ │ Showing 1-5 of 40 issues [< 1 2 3 4 5 ... 8 >] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 3.3 Widget Specifications #### 3.3.1 Issue Pipeline | Attribute | Specification | |-----------|---------------| | **Type** | Horizontal funnel / flow diagram | | **Data Source** | `mv_issue_pipeline` materialized view | | **States** | DETECTED, ACKNOWLEDGED, IN_PROGRESS, RESOLVED, VERIFIED | | **Side States** | DECLINED, REOPENED, STALE (shown separately) | | **Metrics Per State** | Issue count, average time in state | | **Colors** | State-specific (see color scheme) | | **Refresh** | 5 minutes | | **Interactions** | Click state box to filter issue table | **SQL Query**: ```sql SELECT state, COUNT(*) AS issue_count, AVG(EXTRACT(EPOCH FROM (NOW() - state_changed_at)) / 3600) AS avg_hours_in_state FROM issues WHERE deleted_at IS NULL AND state NOT IN ('VERIFIED', 'DECLINED') GROUP BY state ORDER BY CASE state WHEN 'DETECTED' THEN 1 WHEN 'ACKNOWLEDGED' THEN 2 WHEN 'IN_PROGRESS' THEN 3 WHEN 'RESOLVED' THEN 4 ELSE 5 END; ``` #### 3.3.2 SLA Compliance Gauges | Attribute | Specification | |-----------|---------------| | **Type** | Horizontal progress bar with target line | | **Metrics** | TTA Compliance, TTR Compliance, Recurrence Rate | | **Data Source** | Computed from `issues` and `issue_state_history` | | **Target Lines** | Configurable per organization | | **Colors** | Green (>= target), Yellow (within 5%), Red (< target - 5%) | | **Refresh** | 5 minutes | | **Interactions** | Click to see breakdown by domain/team | **TTA Compliance Query**: ```sql WITH tta_data AS ( SELECT i.issue_id, i.max_intensity, EXTRACT(EPOCH FROM (COALESCE(i.acknowledged_at, NOW()) - i.created_at)) / 3600 AS tta_hours, CASE i.max_intensity WHEN 'I3' THEN 4 WHEN 'I2' THEN 24 ELSE 72 END AS target_hours FROM issues i WHERE i.created_at >= NOW() - INTERVAL '30 days' AND i.deleted_at IS NULL ) SELECT COUNT(*) FILTER (WHERE tta_hours <= target_hours) * 100.0 / COUNT(*) AS tta_compliance FROM tta_data; ``` #### 3.3.3 Owner Workload Distribution | Attribute | Specification | |-----------|---------------| | **Type** | Horizontal stacked bar chart | | **Data Source** | `issues` joined with B3 routing config | | **Metrics** | Open issue count, capacity percentage | | **Capacity Config** | Defined per team in configuration | | **Threshold Alerts** | Warning at 70%, Critical at 90% | | **Refresh** | 5 minutes | | **Interactions** | Click row to filter issues by team | #### 3.3.4 Category Breakdown Heatmap | Attribute | Specification | |-----------|---------------| | **Type** | Matrix heatmap | | **Dimensions** | Columns: 7 domains, Rows: 4 category numbers | | **Cell Value** | Count of negative spans in period | | **Color Scale** | White (0) → Light Red → Dark Red (high count) | | **Data Source** | `mv_category_breakdown` | | **Refresh** | 15 minutes | | **Interactions** | Click cell to drill into category Deep-Dive | #### 3.3.5 Active Issues Table | Attribute | Specification | |-----------|---------------| | **Type** | Data grid with sorting, filtering, pagination | | **Library** | AG Grid or React Table | | **Columns** | Issue ID, Subcode, State, Priority, Age, Span Count, Owner | | **Default Sort** | Priority (descending) | | **Filters** | State, Priority range, Domain, Owner, Age range | | **Page Size** | 10, 25, 50, 100 | | **Refresh** | 5 minutes | | **Interactions** | Row click opens issue Deep-Dive, column headers sort | **Table Query**: ```sql SELECT i.issue_id, i.primary_subcode, i.state, i.priority_score, NOW() - i.created_at AS age, i.span_count, i.owner_team, d.name AS domain_name FROM issues i JOIN urt_domains d ON i.domain_code = d.domain_code WHERE i.deleted_at IS NULL AND i.state NOT IN ('VERIFIED', 'DECLINED') ORDER BY i.priority_score DESC; ``` --- ## 4. Analytics Dashboard ### 4.1 Purpose & Key Metrics The Analytics Dashboard provides deep analytical capabilities for trend analysis and anomaly detection. It answers: "What patterns are emerging, and are things getting better or worse?" **Primary Metrics**: - Time-series KPI charts - Comparative Reference (CR) trends - Intensity distribution - Sentiment flow (Sankey) - Anomaly detection alerts ### 4.2 Wireframe ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ URT Dashboard [Analytics v] Period: [Custom v] From:[____] To:[____] │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ TIME-SERIES KPI CHARTS │ │ │ │ │ │ │ │ KPI: [OEI v] Granularity: [Weekly v] Compare: [Previous Period v] │ │ │ │ │ │ │ │ 100 ┤ │ │ │ │ 90 ┤ │ │ │ │ 80 ┤ ___*───*───*───* ___*───*───* │ │ │ │ 70 ┤ *───* *───* │ │ │ │ 60 ┤ *─── │ │ │ │ 50 ┤ │ │ │ │ └──Jan──Feb──Mar──Apr──May──Jun──Jul──Aug──Sep──Oct──Nov──Dec── │ │ │ │ │ │ │ │ ── Current Year -- Previous Year ▓ Target Zone (75-85) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────┐ ┌─────────────────────────────────────┐ │ │ │ COMPARATIVE REFERENCE TRENDS │ │ INTENSITY DISTRIBUTION │ │ │ │ │ │ │ │ │ │ Weekly CR Signal Distribution │ │ This Period vs Previous │ │ │ │ │ │ │ │ │ │ CR-B ████████████ 28% │ │ I1 I2 I3 │ │ │ │ CR-S █████████ 18% │ │ Curr ████ ██████ ██ │ │ │ │ CR-W ████ 8% │ │ 42% 45% 13% │ │ │ │ CR-N ████████████████ 46% │ │ │ │ │ │ │ │ Prev █████ █████ ███ │ │ │ │ ▲ CR-B/CR-W Ratio: 3.5 │ │ 38% 42% 20% │ │ │ │ (Improving from 2.8) │ │ │ │ │ │ │ │ [!] I3 down 7% - good trend │ │ │ │ 12-Week Trend: │ │ │ │ │ │ ───*───*───*───*───*───* │ │ │ │ │ └─────────────────────────────────┘ └─────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ SENTIMENT FLOW (SANKEY DIAGRAM) │ │ │ │ │ │ │ │ Source Domain Valence Outcome │ │ │ │ │ │ │ │ ┌──────┐ │ │ │ │ ┌──────┐ ════╡ O ╞═══╗ ┌──────┐ ┌──────────┐ │ │ │ │ │Google│══════╡ P ╞═══╬════╡ V+ ╞═════╡ Resolved │ │ │ │ │ │ 65% │ ╡ J ╞═══╬════╡ ╞ └──────────┘ │ │ │ │ └──────┘ ════╡ E ╞═══╝ └──────┘ │ │ │ │ ┌──────┐ │ A │ ┌──────┐ ┌──────────┐ │ │ │ │ │ Yelp │══════╡ V ╞════════╡ V- ╞═════╡Open Issue│ │ │ │ │ │ 25% │ ════╡ R ╞═══╗ │ │ └──────────┘ │ │ │ │ └──────┘ └──────┘ ╚════╡ ╞ │ │ │ │ ┌──────┐ └──────┘ ┌──────────┐ │ │ │ │ │Other │══════════════════════════════════╡ Neutral │ │ │ │ │ │ 10% │ └──────────┘ │ │ │ │ └──────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ANOMALY DETECTION ALERTS │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ │ │ [!] CRITICAL: J1.01 (Wait Time) volume +180% vs 7-day avg │ │ │ │ │ │ Detected: 2026-01-23 14:30 | Affected reviews: 23 │ │ │ │ │ │ [View Details] [Acknowledge] [Create Issue] │ │ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ │ │ [!] WARNING: V domain score dropped 5.2 points in 2 weeks │ │ │ │ │ │ Trend: 73.2 → 68.0 | Significance: 95% CI │ │ │ │ │ │ [View Details] [Investigate] │ │ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ │ │ [i] INFO: CR-B surge in O2.05 suggests successful intervention │ │ │ │ │ │ Previous issue: ISSUE-2026-0098 (Resolved 2026-01-15) │ │ │ │ │ │ [View Issue History] │ │ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 4.3 Widget Specifications #### 4.3.1 Time-Series KPI Charts | Attribute | Specification | |-----------|---------------| | **Type** | Line chart with area fill option | | **KPI Options** | OEI, all domain scores, category scores, issue counts | | **Granularity** | Daily, Weekly, Monthly, Quarterly | | **Overlays** | Previous period, target zone, trend line | | **Data Source** | `mv_daily_volume` aggregated to selected granularity | | **Refresh** | 15 minutes | | **Interactions** | Hover for values, zoom, pan, export | #### 4.3.2 Comparative Reference Trends | Attribute | Specification | |-----------|---------------| | **Type** | Stacked bar + ratio line | | **Data Source** | `mv_cr_trends` | | **Metrics** | CR-B, CR-W, CR-S, CR-N percentages; CR-B/CR-W ratio | | **Time Range** | Configurable (default: 12 weeks) | | **Key Insight** | Ratio > 2.0 indicates net improvement | | **Refresh** | 15 minutes | | **Interactions** | Click bar segment to see affected subcodes | **SQL Query**: ```sql SELECT week_start, comparative, SUM(span_count) AS span_count, SUM(span_count) * 100.0 / SUM(SUM(span_count)) OVER (PARTITION BY week_start) AS pct FROM mv_cr_trends WHERE week_start >= NOW() - INTERVAL '12 weeks' GROUP BY week_start, comparative ORDER BY week_start; ``` #### 4.3.3 Intensity Distribution Histogram | Attribute | Specification | |-----------|---------------| | **Type** | Grouped bar chart (current vs previous) | | **Data Source** | `spans` aggregated by intensity | | **Categories** | I1 (Mild), I2 (Moderate), I3 (Strong) | | **Key Insight** | Decreasing I3 percentage indicates improvement | | **Refresh** | 15 minutes | | **Interactions** | Click bar to filter Deep-Dive by intensity | #### 4.3.4 Sentiment Flow Sankey Diagram | Attribute | Specification | |-----------|---------------| | **Type** | Sankey diagram | | **Library** | D3-Sankey or Recharts Sankey | | **Nodes** | Source → Domain → Valence → Outcome | | **Link Width** | Proportional to span count | | **Colors** | Domain colors, valence colors | | **Data Source** | `spans` joined with `issues` and `reviews` | | **Refresh** | 15 minutes | | **Interactions** | Hover links for counts, click to filter | #### 4.3.5 Anomaly Detection Alerts | Attribute | Specification | |-----------|---------------| | **Type** | Alert card list | | **Detection Methods** | Z-score (>2.5), Moving average deviation, Trend break | | **Alert Levels** | Critical (immediate), Warning (24h), Info (monitoring) | | **Data Source** | Real-time anomaly detection service | | **Refresh** | 5 minutes | | **Actions** | View Details, Acknowledge, Create Issue, Dismiss | **Anomaly Detection Logic** (per C2 Section 5.4): ```sql WITH daily_stats AS ( SELECT DATE(created_at) AS span_date, primary_code, COUNT(*) AS daily_count, AVG(COUNT(*)) OVER ( PARTITION BY primary_code ORDER BY DATE(created_at) ROWS BETWEEN 7 PRECEDING AND 1 PRECEDING ) AS moving_avg, STDDEV(COUNT(*)) OVER ( PARTITION BY primary_code ORDER BY DATE(created_at) ROWS BETWEEN 7 PRECEDING AND 1 PRECEDING ) AS moving_stddev FROM spans WHERE valence = 'V-' AND created_at >= NOW() - INTERVAL '30 days' GROUP BY DATE(created_at), primary_code ) SELECT * FROM daily_stats WHERE ABS(daily_count - moving_avg) > 2.5 * NULLIF(moving_stddev, 0); ``` --- ## 5. Deep-Dive Views ### 5.1 Individual Review Annotation Viewer ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ Review Deep-Dive [Print] [Export JSON] [Close X] │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ REVIEW METADATA │ │ │ │ │ │ │ │ Review ID: RVW-2026-04521 Source: Google │ │ │ │ Author: John D. Rating: ★★☆☆☆ (2/5) │ │ │ │ Date: 2026-01-20 Business: Main Street Cafe │ │ │ │ Language: en External ID: CgxKCQ1... │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ANNOTATED REVIEW TEXT │ │ │ │ │ │ │ │ "[The food was cold when it arrived]₁ but [the waiter was very │ │ │ │ apologetic and helpful]₂. [We had to wait 45 minutes for a table │ │ │ │ despite having a reservation]₃." │ │ │ │ │ │ │ │ Legend: [Span 1]₁ = O2.05 [Span 2]₂ = P1.01+R3.02 [Span 3]₃ = J1.01 │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ SPAN DETAILS │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ │ │ SPAN 1: "The food was cold when it arrived" │ │ │ │ │ │ │ │ │ │ │ │ Primary Code: O2.05 (Condition at Delivery) │ │ │ │ │ │ Secondary: None │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Valence │ V- Negative │ Temporal │ TC Current │ │ │ │ │ │ │ │ Intensity │ I2 Moderate │ Evidence │ ES Stated │ │ │ │ │ │ │ │ Specificity │ S2 Moderate │ Comparative │ CR-N None │ │ │ │ │ │ │ │ Actionability│ A2 Medium │ │ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ Linked Issue: ISSUE-2026-0142 [View Issue →] │ │ │ │ │ │ Confidence: 0.92 │ │ │ │ │ │ Annotated By: LLM (claude-3-opus) at 2026-01-20 14:32:00 │ │ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ │ │ SPAN 2: "the waiter was very apologetic and helpful" │ │ │ │ │ │ │ │ │ │ │ │ Primary Code: P1.01 (Warmth/Friendliness) │ │ │ │ │ │ Secondary: R3.02 (Apology) │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Valence │ V+ Positive │ Temporal │ TC Current │ │ │ │ │ │ │ │ Intensity │ I2 Moderate │ Evidence │ ES Stated │ │ │ │ │ │ │ │ Specificity │ S2 Moderate │ Comparative │ CR-N None │ │ │ │ │ │ │ │ Actionability│ A1 Low │ │ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ Linked Issue: None (positive feedback) │ │ │ │ │ │ Confidence: 0.88 │ │ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ [+ Show Span 3] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 5.2 Issue History Timeline ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ Issue Deep-Dive: ISSUE-2026-0142 [Export] [Print] [Close X] │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ISSUE SUMMARY │ │ │ │ │ │ │ │ Issue ID: ISSUE-2026-0142 State: IN_PROGRESS │ │ │ │ Primary Code: O2.05 (Condition) Priority: ████ 5.60 │ │ │ │ Domain: O (Offering) Confidence: 0.88 │ │ │ │ Owner: Kitchen Operations Reopened: 1 time │ │ │ │ │ │ │ │ Entity: Food delivery Location: Main Kitchen │ │ │ │ Created: 2026-01-18 09:15 Last Update: 2 hours ago │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ STATE TIMELINE │ │ │ │ │ │ │ │ ●──────●──────●──────●──────●──────● │ │ │ │ │ │ │ │ │ │ │ │ │ │ DET ACK INP RES REO INP │ │ │ │ 1/18 1/18 1/18 1/19 1/21 1/21 │ │ │ │ │ │ │ │ [+] Jan 18, 09:15 - DETECTED │ │ │ │ Trigger: New V- span (I2) on O2.05 │ │ │ │ Initial spans: 1 │ │ │ │ │ │ │ │ [+] Jan 18, 09:45 - ACKNOWLEDGED │ │ │ │ Actor: kitchen_manager (manual) │ │ │ │ Note: "Third cold food report this week" │ │ │ │ │ │ │ │ [+] Jan 18, 11:00 - IN_PROGRESS │ │ │ │ Actor: kitchen_supervisor │ │ │ │ Note: "Checking heat lamp timers" │ │ │ │ │ │ │ │ [+] Jan 19, 14:30 - RESOLVED │ │ │ │ Actor: kitchen_supervisor │ │ │ │ Resolution: FIX-EQUIPMENT │ │ │ │ Note: "Heat lamps recalibrated, new bags ordered" │ │ │ │ │ │ │ │ [!] Jan 21, 10:15 - REOPENED │ │ │ │ Trigger: CR-S span detected ("Food still cold") │ │ │ │ Span ID: SPN-2026-08742 │ │ │ │ │ │ │ │ [+] Jan 21, 10:30 - IN_PROGRESS │ │ │ │ Actor: kitchen_manager │ │ │ │ Note: "Escalating to delivery process review" │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ CONTRIBUTING SPANS (5) │ │ │ │ │ │ │ │ ┌─────────┬──────────────────────────────────────┬────┬────┬────────┐ │ │ │ │ │ Date │ Span Text (truncated) │ V │ I │ CR │ │ │ │ │ ├─────────┼──────────────────────────────────────┼────┼────┼────────┤ │ │ │ │ │ Jan 18 │ "The food was cold when it arrived" │ V- │ I2 │ CR-N │ │ │ │ │ │ Jan 19 │ "My burger came out cold" │ V- │ I2 │ CR-N │ │ │ │ │ │ Jan 20 │ "Food arrived cold again" │ V- │ I2 │ CR-S │ │ │ │ │ │ Jan 21 │ "Food still arrives cold" │ V- │ I2 │ CR-S │ │ │ │ │ │ Jan 22 │ "Temperature is always bad" │ V- │ I2 │ CR-S │ │ │ │ │ └─────────┴──────────────────────────────────────┴────┴────┴────────┘ │ │ │ │ │ │ │ │ [View All Spans →] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ CAUSAL CHAIN (if assigned) │ │ │ │ │ │ │ │ Experience → Conditions → Management → Systemic │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ O2.05 │ ───► │ CD-E │ ───► │ MG-R │ ───► │ SY-R │ │ │ │ │ │Condition │ │Equipment │ │Resources │ │ Budget │ │ │ │ │ │at Deliv. │ │ │ │ │ │ │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ │ Chain Confidence: 0.75 │ │ │ │ Analyst Note: "Heat lamps outdated, replacement budget pending" │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ ACTIONS │ │ │ │ │ │ │ │ [Acknowledge] [Start Work] [Resolve] [Decline] [Add Note] [Reassign] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 5.3 Causal Chain Visualization ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ Causal Chain Analysis [Close X] │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ CAUSAL CHAIN DIAGRAM │ │ │ │ │ │ │ │ LAYER 1 LAYER 2 LAYER 3 LAYER 4│ │ │ EXPERIENCE CONDITIONS MANAGEMENT SYSTEMIC│ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐│ │ │ │ │ O2.05 │ ┌───▶│ CD-E │ ┌───▶│ MG-R │ ┌───▶│ SY-R ││ │ │ │ │Condition │────┤ │Equipment │────┤ │Resources │────┤ │Budget││ │ │ │ │at Deliv. │ │ │Malfunction│ │ │Maintenance│ │ │ ││ │ │ │ └──────────┘ │ └──────────┘ │ └──────────┘ │ └──────┘│ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌──────────┐ │ ┌──────────┐ │ ┌──────┐│ │ │ │ └──────────┼───▶│ CD-O │────┼───▶│ MG-P │────┴───▶│ SY-H ││ │ │ │ │ │Operational│ │ │Planning │ │Human ││ │ │ │ │ │Understaffed│ │ │Scheduling│ │Capital│ │ │ │ │ └──────────┘ │ └──────────┘ └──────┘│ │ │ │ │ │ │ │ │ │ │ ┌──────────┐ │ │ │ │ │ └───▶│ CD-S │────┘ │ │ │ │ │Staff State│ │ │ │ │ │Fatigue │ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ ─────────────────────────────────────────────────────────────────── │ │ │ │ │ │ │ │ CHAIN STATISTICS: │ │ │ │ │ │ │ │ Most Common Paths: │ │ │ │ 1. O2.05 → CD-E → MG-R → SY-R (45% of similar issues) │ │ │ │ 2. O2.05 → CD-O → MG-P → SY-H (30% of similar issues) │ │ │ │ 3. O2.05 → CD-S → MG-T → SY-C (15% of similar issues) │ │ │ │ │ │ │ │ Recommended Intervention Level: MANAGEMENT (MG-R) │ │ │ │ Reason: 70% of paths converge at resource management │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 6. Widget Specifications ### 6.1 Gauge Widget ``` ┌─────────────────────────────────────────────────────────────────┐ │ GAUGE WIDGET SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: │ │ ╭─────────────────────────────╮ │ │ ╱ ░░░░░░░░ ╲ │ │ ╱ ░░░░░░░ ░░░░░░░ ╲ │ │ │ ░░░ ▲ ░░░ │ │ │ │ ░░ ╱▔▔▔▔▔▔▔▔▔╲ ░░ │ │ │ │░ ╱ 79.9 ╲ ░│ │ │ │ ╱ ╲ │ │ │ ╲╱ ╲╱ │ │ ████████████████████░░░░░░░░░ │ │ Red Yellow Green Blue │ │ 0 50 65 85 100 │ │ │ │ Components: │ │ ├── Arc: SVG path with gradient │ │ ├── Needle: SVG line with rotation transform │ │ ├── Value: Centered text │ │ ├── Delta: Below value with arrow │ │ ├── Labels: Min/Max/Target markers │ │ └── Background: Semi-transparent fill │ │ │ │ Props: │ │ ├── value: number (0-100) │ │ ├── previousValue?: number (for delta) │ │ ├── ranges: Array<{min, max, color}> │ │ ├── targetValue?: number (optional target line) │ │ ├── size: 'sm' | 'md' | 'lg' │ │ └── onDrillDown?: () => void │ │ │ │ Responsive: │ │ ├── lg (>1200px): 200x120 │ │ ├── md (768-1199px): 160x100 │ │ └── sm (<768px): 120x80 │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 6.2 Radar Chart Widget ``` ┌─────────────────────────────────────────────────────────────────┐ │ RADAR CHART WIDGET SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Library: Recharts RadarChart │ │ │ │ Configuration: │ │ { │ │ data: [ │ │ { domain: 'O', current: 82, previous: 79, target: 80 }, │ │ { domain: 'P', current: 88, previous: 86, target: 85 }, │ │ { domain: 'J', current: 75, previous: 76, target: 75 }, │ │ { domain: 'E', current: 80, previous: 78, target: 80 }, │ │ { domain: 'A', current: 85, previous: 85, target: 85 }, │ │ { domain: 'V', current: 68, previous: 70, target: 70 }, │ │ { domain: 'R', current: 78, previous: 77, target: 80 } │ │ ], │ │ angleKey: 'domain', │ │ series: [ │ │ { key: 'current', stroke: '#3B82F6', fill: '#3B82F680' }, │ │ { key: 'previous', stroke: '#9CA3AF', strokeDash: '5,5' },│ │ { key: 'target', stroke: '#10B981', strokeDash: '2,2' } │ │ ] │ │ } │ │ │ │ Interactions: │ │ ├── Hover axis: Show domain tooltip with score details │ │ ├── Click axis: Navigate to domain-filtered Operations │ │ └── Legend toggle: Show/hide series │ │ │ │ Responsive: │ │ ├── lg: 400x400 │ │ ├── md: 300x300 │ │ └── sm: 250x250 (stacked with score cards) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 6.3 Data Grid Widget ``` ┌─────────────────────────────────────────────────────────────────┐ │ DATA GRID WIDGET SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Library: AG Grid Community │ │ │ │ Column Definitions (Issues Table): │ │ [ │ │ { field: 'issue_id', headerName: 'Issue ID', width: 130, │ │ cellRenderer: 'issueLinkRenderer' }, │ │ { field: 'primary_subcode', headerName: 'Subcode', width: 90,│ │ cellRenderer: 'subcodeChipRenderer' }, │ │ { field: 'state', headerName: 'State', width: 100, │ │ cellRenderer: 'stateBadgeRenderer' }, │ │ { field: 'priority_score', headerName: 'Priority', width: 120│ │ cellRenderer: 'priorityBarRenderer', sort: 'desc' }, │ │ { field: 'age', headerName: 'Age', width: 80, │ │ valueFormatter: formatDuration }, │ │ { field: 'span_count', headerName: 'Spans', width: 70 }, │ │ { field: 'owner_team', headerName: 'Owner', width: 120 } │ │ ] │ │ │ │ Grid Options: │ │ { │ │ pagination: true, │ │ paginationPageSize: 10, │ │ paginationPageSizeSelector: [10, 25, 50, 100], │ │ rowSelection: 'single', │ │ onRowClicked: (event) => openIssueDeepDive(event.data), │ │ defaultColDef: { sortable: true, filter: true, resizable: true│ │ } │ │ │ │ Custom Renderers: │ │ ├── issueLinkRenderer: Clickable link to Deep-Dive │ │ ├── subcodeChipRenderer: Colored chip with domain color │ │ ├── stateBadgeRenderer: State-colored badge │ │ └── priorityBarRenderer: Mini horizontal bar chart │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 6.4 Sparkline Widget ``` ┌─────────────────────────────────────────────────────────────────┐ │ SPARKLINE WIDGET SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: ~~~~~~* │ │ │ │ Library: Recharts LineChart (minimal config) │ │ │ │ Configuration: │ │ { │ │ data: Array<{ date: string, value: number }>, │ │ width: 80, │ │ height: 24, │ │ margin: { top: 2, bottom: 2, left: 0, right: 0 }, │ │ stroke: determineStrokeColor(trend), │ │ strokeWidth: 1.5, │ │ dot: { r: 2 } // Only on last point │ │ } │ │ │ │ Color Logic: │ │ ├── Positive trend (last > first): Green (#10B981) │ │ ├── Negative trend (last < first): Red (#EF4444) │ │ └── Stable (|delta| < 2%): Gray (#6B7280) │ │ │ │ Props: │ │ ├── data: Array<{date, value}> │ │ ├── color?: 'auto' | string │ │ └── showEndpoint?: boolean (default: true) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 6.5 Alert Card Widget ``` ┌─────────────────────────────────────────────────────────────────┐ │ ALERT CARD WIDGET SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ [!] CRITICAL: J1.01 (Wait Time) volume +180% │ │ │ │ Detected: 2026-01-23 14:30 | Affected: 23 reviews │ │ │ │ [View Details] [Acknowledge] [Create Issue] │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ Severity Styles: │ │ ├── CRITICAL: Red border left, red icon, red highlight │ │ ├── WARNING: Yellow border left, yellow icon │ │ ├── INFO: Blue border left, blue icon │ │ └── SUCCESS: Green border left, green icon │ │ │ │ Props: │ │ { │ │ severity: 'critical' | 'warning' | 'info' | 'success', │ │ title: string, │ │ description: string, │ │ timestamp: Date, │ │ metadata?: Record, │ │ actions: Array<{label: string, onClick: () => void}> │ │ } │ │ │ │ Accessibility: │ │ ├── role="alert" for critical/warning │ │ ├── aria-live="polite" for new alerts │ │ └── Focus management for action buttons │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 7. Color Schemes ### 7.1 Domain Color Palette Each domain has a primary, secondary, and light variant for consistent visual identity. | Domain | Code | Primary (Dark) | Secondary (Medium) | Light (Background) | Meaning | |--------|------|----------------|--------------------|--------------------|---------| | **Offering** | O | `#2563EB` | `#3B82F6` | `#DBEAFE` | Blue (Product) | | **People** | P | `#7C3AED` | `#8B5CF6` | `#EDE9FE` | Purple (Human) | | **Journey** | J | `#0891B2` | `#06B6D4` | `#CFFAFE` | Cyan (Process) | | **Environment** | E | `#059669` | `#10B981` | `#D1FAE5` | Green (Space) | | **Access** | A | `#D97706` | `#F59E0B` | `#FEF3C7` | Amber (Reach) | | **Value** | V | `#DC2626` | `#EF4444` | `#FEE2E2` | Red (Cost) | | **Relationship** | R | `#DB2777` | `#EC4899` | `#FCE7F3` | Pink (Trust) | ### 7.2 Valence Colors | Valence | Code | Color | Hex | Use Case | |---------|------|-------|-----|----------| | **Positive** | V+ | Green | `#10B981` | Praise, satisfaction | | **Negative** | V- | Red | `#EF4444` | Complaints, issues | | **Neutral** | V0 | Gray | `#6B7280` | Observations | | **Mixed** | V+/- | Yellow | `#F59E0B` | Ambiguous feedback | ### 7.3 Intensity Gradients | Intensity | Code | Color | Opacity | Visual | |-----------|------|-------|---------|--------| | **Mild** | I1 | Base | 40% | Light shade | | **Moderate** | I2 | Base | 70% | Medium shade | | **Strong** | I3 | Base | 100% | Full saturation | **CSS Variables**: ```css :root { /* Intensity modifiers */ --intensity-i1-opacity: 0.4; --intensity-i2-opacity: 0.7; --intensity-i3-opacity: 1.0; /* Combined with valence */ --positive-i1: rgba(16, 185, 129, 0.4); --positive-i2: rgba(16, 185, 129, 0.7); --positive-i3: rgba(16, 185, 129, 1.0); --negative-i1: rgba(239, 68, 68, 0.4); --negative-i2: rgba(239, 68, 68, 0.7); --negative-i3: rgba(239, 68, 68, 1.0); } ``` ### 7.4 Alert State Colors | Alert Level | Background | Border | Icon | Text | |-------------|------------|--------|------|------| | **Critical** | `#FEF2F2` | `#EF4444` | `#DC2626` | `#991B1B` | | **Warning** | `#FFFBEB` | `#F59E0B` | `#D97706` | `#92400E` | | **Info** | `#EFF6FF` | `#3B82F6` | `#2563EB` | `#1E40AF` | | **Success** | `#F0FDF4` | `#10B981` | `#059669` | `#166534` | ### 7.5 Issue State Colors | State | Color | Hex | Icon | |-------|-------|-----|------| | **DETECTED** | Orange | `#F97316` | Circle outline | | **ACKNOWLEDGED** | Blue | `#3B82F6` | Eye icon | | **IN_PROGRESS** | Yellow | `#EAB308` | Spinning loader | | **RESOLVED** | Green | `#22C55E` | Check circle | | **VERIFIED** | Green (dark) | `#15803D` | Double check | | **DECLINED** | Gray | `#6B7280` | X circle | | **REOPENED** | Red | `#EF4444` | Refresh icon | | **STALE** | Gray (light) | `#9CA3AF` | Clock icon | ### 7.6 Score Range Colors | Range | Level | Background | Text | |-------|-------|------------|------| | 85-100 | Excellent | `#DCFCE7` | `#166534` | | 75-84 | Good | `#D1FAE5` | `#065F46` | | 65-74 | Acceptable | `#FEF3C7` | `#92400E` | | 50-64 | Poor | `#FEE2E2` | `#991B1B` | | 0-49 | Critical | `#FEE2E2` | `#7F1D1D` | --- ## 8. Filter Components ### 8.1 Date Range Picker ``` ┌─────────────────────────────────────────────────────────────────┐ │ DATE RANGE PICKER SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: │ │ ┌────────────────────────────────────────────────────────────┐│ │ │ Period: [Last 30 days ▼] From: [01/01/2026] To: [01/23/26]││ │ └────────────────────────────────────────────────────────────┘│ │ │ │ Preset Options: │ │ ├── Today │ │ ├── Yesterday │ │ ├── Last 7 days │ │ ├── Last 30 days (default) │ │ ├── Last 90 days │ │ ├── This month │ │ ├── Last month │ │ ├── This quarter │ │ ├── Last quarter │ │ ├── This year │ │ ├── Last year │ │ └── Custom range │ │ │ │ Comparison Options: │ │ ├── Previous period (same length) │ │ ├── Same period last year │ │ └── None │ │ │ │ Props: │ │ { │ │ value: { from: Date, to: Date }, │ │ onChange: (range) => void, │ │ presets: PresetOption[], │ │ comparison?: 'previous' | 'year_ago' | 'none', │ │ maxRange?: number (days), │ │ minDate?: Date, │ │ maxDate?: Date │ │ } │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 8.2 Domain/Category/Subcode Selector ``` ┌─────────────────────────────────────────────────────────────────┐ │ HIERARCHICAL CODE SELECTOR SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Domain: [All ▼] Category: [All ▼] Subcode: [All ▼] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ Cascading Behavior: │ │ 1. Domain selection filters available categories │ │ 2. Category selection filters available subcodes │ │ 3. Subcode selection auto-sets domain and category │ │ │ │ Domain Dropdown: │ │ ┌─────────────────────┐ │ │ │ ☐ All Domains │ │ │ │ ☑ O - Offering │ ← Colored chip │ │ │ ☐ P - People │ │ │ │ ☑ J - Journey │ │ │ │ ... │ │ │ └─────────────────────┘ │ │ │ │ Props: │ │ { │ │ value: { │ │ domains: string[], │ │ categories: string[], │ │ subcodes: string[] │ │ }, │ │ onChange: (selection) => void, │ │ allowMultiple: boolean, │ │ showCounts: boolean (show span/issue counts per option) │ │ } │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 8.3 Valence and Intensity Filters ``` ┌─────────────────────────────────────────────────────────────────┐ │ VALENCE/INTENSITY FILTER SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual (Toggle Buttons): │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Valence: [V+] [V-] [V0] [V±] Intensity: [I1] [I2] [I3]│ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ Active states shown with filled background and border │ │ │ │ Default: All selected (no filter) │ │ │ │ Props: │ │ { │ │ valence: ('V+' | 'V-' | 'V0' | 'V±')[], │ │ intensity: ('I1' | 'I2' | 'I3')[], │ │ onChange: (filters) => void │ │ } │ │ │ │ Quick Actions: │ │ ├── "Negative Only" → V- selected │ │ ├── "Critical Only" → V- + I3 selected │ │ └── "Clear All" → All selected │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 8.4 Owner/Team Filter ``` ┌─────────────────────────────────────────────────────────────────┐ │ OWNER/TEAM FILTER SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Owner: [All Teams ▼] Individual: [All ▼] │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ Data Source: B3-owner-routing.yaml teams configuration │ │ │ │ Team Options: │ │ ├── Operations │ │ ├── HR/Training │ │ ├── Product │ │ ├── Engineering │ │ ├── Facilities │ │ ├── Finance │ │ ├── CX Leadership │ │ └── (custom teams from config) │ │ │ │ Individual: Populated based on team selection │ │ │ │ Props: │ │ { │ │ teams: string[], │ │ individuals: string[], │ │ onChange: (filters) => void │ │ } │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 8.5 Issue State Filter ``` ┌─────────────────────────────────────────────────────────────────┐ │ ISSUE STATE FILTER SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual (Pill Toggle): │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ [All] [Open] [DET] [ACK] [INP] [RES] [VER] [DEC] [REO] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ Presets: │ │ ├── "All": No filter │ │ ├── "Open": DETECTED, ACKNOWLEDGED, IN_PROGRESS, REOPENED │ │ ├── "Pending": RESOLVED (awaiting verification) │ │ └── "Closed": VERIFIED, DECLINED │ │ │ │ State pills show count badges │ │ │ │ Props: │ │ { │ │ selectedStates: IssueState[], │ │ onChange: (states) => void, │ │ showCounts: boolean │ │ } │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 8.6 Comparative Reference Filter ``` ┌─────────────────────────────────────────────────────────────────┐ │ COMPARATIVE REFERENCE FILTER SPECIFICATION │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Visual: │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ CR Signal: [All ▼] │ │ │ │ ├── All (no filter) │ │ │ │ ├── Has Comparison (CR-B, CR-W, CR-S) │ │ │ │ ├── Improving (CR-B only) │ │ │ │ ├── Worsening (CR-W only) │ │ │ │ ├── Persistent (CR-S only) │ │ │ │ └── No Comparison (CR-N only) │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ Use Case: Identify improvement opportunities and regressions │ │ │ │ Props: │ │ { │ │ selected: ('CR-N' | 'CR-B' | 'CR-W' | 'CR-S')[], │ │ onChange: (cr) => void │ │ } │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 8.7 Global Filter Bar ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ GLOBAL FILTER BAR LAYOUT │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ Desktop (≥1200px): │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ [Date Range ▼] [Domain ▼] [State ▼] [Valence ▼] [Owner ▼] [⚙ More] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ Tablet (768-1199px): │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ [Date Range ▼] [Domain ▼] [State ▼] [+ 3 more filters] │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ Mobile (<768px): │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ [Filters (5 active) ▼] ← Opens filter drawer │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ Active Filter Pills: │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Last 30 days × | Domain: O, J × | State: Open × | Valence: V- × | Clear│ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ State Management: │ │ ├── URL params sync for shareable views │ │ ├── Local storage for user preferences │ │ └── Reset to defaults button │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 9. Data Requirements ### 9.1 API Endpoints | Endpoint | Method | Purpose | Dashboard | Refresh | |----------|--------|---------|-----------|---------| | `/api/v1/kpi/oei` | GET | Overall Experience Index | Executive | 15 min | | `/api/v1/kpi/domains` | GET | All domain scores | Executive, Ops | 15 min | | `/api/v1/kpi/categories/{domain}` | GET | Category breakdown | Operations | 15 min | | `/api/v1/kpi/trends` | GET | Time-series data | Analytics | 15 min | | `/api/v1/issues` | GET | Issue list with filters | Operations | 5 min | | `/api/v1/issues/{id}` | GET | Issue detail | Deep-Dive | On-demand | | `/api/v1/issues/{id}/history` | GET | State history | Deep-Dive | On-demand | | `/api/v1/spans` | GET | Span list with filters | Analytics | 15 min | | `/api/v1/spans/{id}` | GET | Span detail | Deep-Dive | On-demand | | `/api/v1/reviews/{id}` | GET | Review with spans | Deep-Dive | On-demand | | `/api/v1/alerts` | GET | Active alerts | All | 5 min | | `/api/v1/alerts/{id}/acknowledge` | POST | Acknowledge alert | All | — | | `/api/v1/cr/trends` | GET | CR signal trends | Analytics | 15 min | | `/api/v1/anomalies` | GET | Detected anomalies | Analytics | 5 min | | `/api/v1/workload` | GET | Team workload | Operations | 5 min | ### 9.2 Query Parameters (Common) | Parameter | Type | Description | Example | |-----------|------|-------------|---------| | `from` | ISO Date | Start date | `2026-01-01` | | `to` | ISO Date | End date | `2026-01-23` | | `domains` | String[] | Domain filter | `O,P,J` | | `categories` | String[] | Category filter | `O1,O2` | | `subcodes` | String[] | Subcode filter | `O1.01,O1.02` | | `valence` | String[] | Valence filter | `V-,V±` | | `intensity` | String[] | Intensity filter | `I2,I3` | | `state` | String[] | Issue state filter | `DETECTED,IN_PROGRESS` | | `owner` | String | Team/owner filter | `operations` | | `limit` | Integer | Page size | `25` | | `offset` | Integer | Page offset | `0` | | `sort` | String | Sort field | `priority_score` | | `order` | String | Sort direction | `desc` | ### 9.3 WebSocket Events (Real-time) | Event | Payload | Trigger | Dashboard | |-------|---------|---------|-----------| | `issue.created` | Issue summary | New issue detected | Operations | | `issue.state_changed` | Issue ID, old/new state | State transition | Operations | | `alert.triggered` | Alert details | Anomaly detected | All | | `kpi.updated` | Domain, new value | MV refresh complete | Executive | | `span.classified` | Span summary | New span processed | Analytics | ### 9.4 Polling Intervals | Dashboard | Data Type | Interval | Method | |-----------|-----------|----------|--------| | Executive | KPIs, OEI | 15 min | Polling | | Executive | Alerts | 5 min | Polling + WebSocket | | Operations | Issue list | 5 min | Polling | | Operations | Pipeline | 5 min | Polling | | Operations | Workload | 5 min | Polling | | Analytics | Time-series | 15 min | Polling | | Analytics | Anomalies | 5 min | WebSocket | | Deep-Dive | All data | On-demand | Request | ### 9.5 Caching Strategy ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ CACHING ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ LAYER 1: Client-Side (Browser) │ │ ├── React Query / SWR for request deduplication │ │ ├── staleTime: 5 minutes (for most queries) │ │ ├── cacheTime: 30 minutes │ │ └── refetchOnWindowFocus: true │ │ │ │ LAYER 2: API Gateway (Redis) │ │ ├── KPI aggregations: 5 minute TTL │ │ ├── Issue counts: 2 minute TTL │ │ ├── Reference data (domains, categories): 1 hour TTL │ │ └── User preferences: 24 hour TTL │ │ │ │ LAYER 3: Database (PostgreSQL) │ │ ├── Materialized Views: Refreshed every 5-15 minutes │ │ │ ├── mv_domain_summary: 15 min │ │ │ ├── mv_category_breakdown: 15 min │ │ │ ├── mv_issue_pipeline: 5 min │ │ │ ├── mv_cr_trends: 15 min │ │ │ └── mv_daily_volume: 15 min │ │ └── pg_cron job: REFRESH MATERIALIZED VIEW CONCURRENTLY │ │ │ │ Cache Invalidation: │ │ ├── Issue state change → Invalidate pipeline cache │ │ ├── New span classified → Invalidate domain/category caches │ │ └── Alert triggered → Broadcast WebSocket, invalidate alert cache │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 9.6 Data Source Mapping | Widget | Primary Table/View | Fallback | Notes | |--------|-------------------|----------|-------| | OEI Gauge | `mv_domain_summary` | Computed from `spans` | Prefer MV | | Domain Radar | `mv_domain_summary` | — | — | | Domain Cards | `mv_domain_summary` | — | — | | Issue Pipeline | `mv_issue_pipeline` | `issues` grouped | MV preferred | | SLA Gauges | `issues` + `issue_state_history` | — | Computed | | Workload | `issues` + routing config | — | Live query | | Heatmap | `mv_category_breakdown` | — | — | | Issue Table | `issues` JOIN `urt_domains` | — | Paginated | | Time-series | `mv_daily_volume` | `spans` grouped | MV preferred | | CR Trends | `mv_cr_trends` | `spans` filtered | MV preferred | | Anomalies | Anomaly detection service | — | Real-time | | Sankey | `spans` + `issues` + `reviews` | — | Complex query | --- ## 10. User Roles & Permissions ### 10.1 Role Definitions | Role | Description | Default Users | |------|-------------|---------------| | **executive** | Strategic overview, read-only | C-Suite, Directors | | **operations** | Issue management, full write | Managers, Team Leads | | **analyst** | Deep analytics, export | Data Analysts, BI Team | | **admin** | Full access, configuration | System Administrators | | **viewer** | Read-only basic access | General staff | ### 10.2 Permission Matrix | Feature | Viewer | Executive | Operations | Analyst | Admin | |---------|--------|-----------|------------|---------|-------| | View Executive Dashboard | ✓ | ✓ | ✓ | ✓ | ✓ | | View Operations Dashboard | ✓ | ✓ | ✓ | ✓ | ✓ | | View Analytics Dashboard | — | ✓ | ✓ | ✓ | ✓ | | View Deep-Dive | — | ✓ | ✓ | ✓ | ✓ | | Acknowledge Issues | — | — | ✓ | — | ✓ | | Change Issue State | — | — | ✓ | — | ✓ | | Assign Issues | — | — | ✓ | — | ✓ | | Add Issue Notes | — | ✓ | ✓ | ✓ | ✓ | | Acknowledge Alerts | — | ✓ | ✓ | ✓ | ✓ | | Create Issues from Alerts | — | — | ✓ | — | ✓ | | Export Data | — | ✓ | ✓ | ✓ | ✓ | | Configure Alerts | — | — | — | — | ✓ | | Manage Users | — | — | — | — | ✓ | | Configure Routing | — | — | — | — | ✓ | | View Audit Logs | — | — | — | ✓ | ✓ | ### 10.3 Dashboard Access by Role ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ ROLE-BASED DASHBOARD ACCESS │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ VIEWER │ │ ├── Executive Dashboard (read-only) │ │ └── Operations Dashboard (read-only, no actions) │ │ │ │ EXECUTIVE │ │ ├── Executive Dashboard (default landing) │ │ ├── Operations Dashboard (read, add notes) │ │ ├── Analytics Dashboard (read, export) │ │ └── Deep-Dive Views (read) │ │ │ │ OPERATIONS │ │ ├── Operations Dashboard (default landing, full control) │ │ ├── Executive Dashboard (read) │ │ ├── Analytics Dashboard (read) │ │ └── Deep-Dive Views (read, manage issues) │ │ │ │ ANALYST │ │ ├── Analytics Dashboard (default landing, full features) │ │ ├── Executive Dashboard (read) │ │ ├── Operations Dashboard (read) │ │ ├── Deep-Dive Views (read, add notes) │ │ └── Custom Report Builder (if available) │ │ │ │ ADMIN │ │ ├── All dashboards with full access │ │ ├── Settings & Configuration │ │ ├── User Management │ │ └── Audit Logs │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 10.4 Data Filtering by Role | Role | Data Scope | Rationale | |------|------------|-----------| | **viewer** | All domains, no PII | General awareness | | **executive** | All domains, aggregate only | Strategic overview | | **operations** | All domains, full detail | Issue management | | **analyst** | All domains, full detail + history | Deep analysis | | **admin** | All data including system logs | Full visibility | ### 10.5 Team-Based Filtering Operations users may be restricted to issues owned by their team: ``` IF user.role == 'operations' AND user.teamScope != 'all': issues = issues.filter(owner_team IN user.teams) alerts = alerts.filter(relevant_team IN user.teams) ``` --- ## 11. Responsive Design ### 11.1 Breakpoints | Breakpoint | Width | Layout | Target Devices | |------------|-------|--------|----------------| | **xs** | <576px | Single column | Mobile portrait | | **sm** | 576-767px | Single column | Mobile landscape | | **md** | 768-1199px | 2 columns | Tablet | | **lg** | 1200-1439px | 3 columns | Small desktop | | **xl** | ≥1440px | Full layout | Desktop, Large monitors | ### 11.2 Executive Dashboard Responsive Layouts ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ EXECUTIVE DASHBOARD - RESPONSIVE LAYOUTS │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ XL (≥1440px): Full 3-Column Layout │ │ ┌──────────────┬──────────────┬──────────────┐ │ │ │ OEI Gauge │ Radar Chart │ Alerts │ │ │ ├──────────────┴──────────────┴──────────────┤ │ │ │ 7 Domain Score Cards (row) │ │ │ ├────────────────────────────────────────────┤ │ │ │ 12-Week Trend Line │ │ │ ├──────────────────────┬─────────────────────┤ │ │ │ Composite Indices │ Quick Stats │ │ │ └──────────────────────┴─────────────────────┘ │ │ │ │ MD (768-1199px): 2-Column Layout │ │ ┌──────────────┬──────────────┐ │ │ │ OEI Gauge │ Radar Chart │ │ │ ├──────────────┴──────────────┤ │ │ │ Domain Cards (2x4 grid) │ │ │ ├──────────────┬──────────────┤ │ │ │ Alerts │ Trends │ │ │ ├──────────────┴──────────────┤ │ │ │ Trend Line │ │ │ └─────────────────────────────┘ │ │ │ │ SM/XS (<768px): Single Column, Stacked │ │ ┌─────────────────────────────┐ │ │ │ OEI Gauge (large) │ │ │ ├─────────────────────────────┤ │ │ │ Domain Cards (carousel) │ ← Swipeable │ │ ├─────────────────────────────┤ │ │ │ Alerts (collapsible) │ │ │ ├─────────────────────────────┤ │ │ │ Trend Line (scrollable) │ │ │ └─────────────────────────────┘ │ │ Note: Radar chart hidden on mobile, replaced by domain cards │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 11.3 Operations Dashboard Responsive Layouts ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ OPERATIONS DASHBOARD - RESPONSIVE LAYOUTS │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ XL (≥1440px): Full Layout │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Issue Pipeline (horizontal) │ │ │ ├───────────────────────────────┬─────────────────────────────────────────┤ │ │ │ SLA Gauges (3 stack) │ Owner Workload (bar chart) │ │ │ ├───────────────────────────────┴─────────────────────────────────────────┤ │ │ │ Category Heatmap (7x4 grid) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Issue Table (full width) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ MD (768-1199px): Stacked Sections │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Issue Pipeline (compact) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ SLA Gauges │ Owner Workload │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Category Heatmap (scrollable) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Issue Table (horizontal scroll) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ SM/XS (<768px): Mobile-First │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Pipeline Summary (counts only, no visualization) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ SLA Compliance (single combined gauge) │ │ │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Issue Cards (list view, swipe actions) │ │ │ │ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ │ │ ISSUE-0142 │ O2.05 │ INP │ ████ 5.60 │ 3d │ [→ Swipe for actions]│ │ │ │ │ └───────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 11.4 Touch Interactions (Mobile) | Gesture | Action | Context | |---------|--------|---------| | **Tap** | Select / Open | All interactive elements | | **Long Press** | Context menu | Issue cards, spans | | **Swipe Left** | Quick actions (Ack, Assign) | Issue cards | | **Swipe Right** | Dismiss / Archive | Alerts | | **Pinch Zoom** | Zoom charts | Time-series, Sankey | | **Pull Down** | Refresh data | All dashboards | | **Two-finger Pan** | Pan zoomed charts | Analytics charts | --- ## 12. Implementation Notes ### 12.1 Accessibility Requirements | Requirement | Implementation | |-------------|----------------| | **Keyboard Navigation** | All interactive elements focusable, logical tab order | | **Screen Reader** | ARIA labels, roles, live regions for updates | | **Color Contrast** | WCAG 2.1 AA minimum (4.5:1 for text) | | **Focus Indicators** | Visible focus rings on all focusable elements | | **Skip Links** | Skip to main content, skip to navigation | | **Alternative Text** | Descriptive alt text for all charts/images | | **Reduced Motion** | Respect `prefers-reduced-motion` media query | ### 12.2 Performance Targets | Metric | Target | Measurement | |--------|--------|-------------| | **First Contentful Paint** | <1.5s | Lighthouse | | **Time to Interactive** | <3.0s | Lighthouse | | **Largest Contentful Paint** | <2.5s | Lighthouse | | **API Response Time** | <200ms (p95) | Server metrics | | **Chart Render Time** | <100ms | Performance API | | **Bundle Size** | <500KB (gzipped) | Webpack analyzer | ### 12.3 Error Handling ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ ERROR HANDLING PATTERNS │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ API Errors: │ │ ├── 4xx: Show user-friendly message, offer retry │ │ ├── 5xx: Show error boundary, log to monitoring │ │ └── Timeout: Show "Taking longer than expected", auto-retry │ │ │ │ Widget Errors: │ │ ├── Data missing: Show placeholder with "No data available" │ │ ├── Parse error: Show fallback component, log error │ │ └── Render error: Error boundary catches, shows widget skeleton │ │ │ │ Real-time Errors: │ │ ├── WebSocket disconnect: Auto-reconnect with exponential backoff │ │ ├── Missed events: Request full refresh on reconnect │ │ └── Stale data: Show "Data may be outdated" indicator │ │ │ │ User Feedback: │ │ ├── Toast notifications for transient errors │ │ ├── Inline error messages for form validation │ │ └── Full-page error for critical failures │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ### 12.4 Testing Strategy | Test Type | Coverage | Tools | |-----------|----------|-------| | **Unit Tests** | Widget components, utilities | Jest, React Testing Library | | **Integration Tests** | API interactions, state management | MSW, Cypress Component | | **E2E Tests** | Critical user flows | Cypress, Playwright | | **Visual Regression** | UI consistency | Percy, Chromatic | | **Accessibility Tests** | WCAG compliance | axe-core, Pa11y | | **Performance Tests** | Load time, render performance | Lighthouse CI | ### 12.5 Deployment Considerations | Aspect | Recommendation | |--------|----------------| | **CDN** | Static assets via CloudFront/Cloudflare | | **API** | Load-balanced behind API gateway | | **Database** | Read replicas for dashboard queries | | **Caching** | Redis cluster for API response caching | | **Monitoring** | DataDog/New Relic for APM | | **Logging** | Structured JSON logs to centralized system | | **Feature Flags** | LaunchDarkly for gradual rollout | ### 12.6 Future Enhancements | Enhancement | Priority | Description | |-------------|----------|-------------| | **Custom Dashboards** | Medium | User-configurable widget layouts | | **Report Builder** | Medium | Drag-and-drop report creation | | **Scheduled Reports** | Medium | Email/Slack delivery of snapshots | | **Embedding** | Low | Embed widgets in external tools | | **Mobile App** | Low | Native iOS/Android app | | **AI Insights** | High | Automated insight generation | | **Predictive Analytics** | High | Issue prediction, churn risk | --- ## Document Control | Field | Value | |-------|-------| | **Document** | D1 - Dashboard Specification | | **Version** | 1.0 | | **Status** | Production Ready | | **Date** | 2026-01-23 | | **Author** | URT Working Group | | **Part Of** | Track D: Integration Layer | --- ## Related Documents | Document | Purpose | Status | |----------|---------|--------| | **B2-database-schema.sql** | Database tables and views | Complete | | **B3-owner-routing.md** | Team routing configuration | Complete | | **C1-Issue-Lifecycle-Framework.md** | Issue state management | Complete | | **C2-KPI-Mapping-Guide.md** | KPI calculations and alerts | Complete | | **D2-API-Specification** | API endpoint details | Planned | | **D3-Integration-Guide** | Third-party integrations | Planned | --- *End of D1: Dashboard Specification*