ADR-005: ITSM Dashboard Data Flow Architecture

Status: Proposed Date: 2026-01-24 Deciders: @cloud-architect, @product-owner, HITL/Manager

Context

Cloud-Infrastructure project requires ITSM (IT Service Management) dashboard to visualize Jira Service Management tickets from Azure (541 tickets) and AWS (2,458 tickets) projects.

Current State

• Data Source: Excel exports from Jira (manual export workflow)
• Azure: 541 tickets (dashboards/itsm/architecture/Azure-Tickets.xlsx)
• AWS: 2,458 tickets (dashboards/itsm/architecture/AWS-Tickets.xlsx)
• Schema: 17 fields (ticket ID, status, priority, assignee, created, resolved, SLA, etc.)
• Mockup: Dashboard-JSM.png shows KPI cards, trend charts, data tables
• Existing Skill: jira-itsm-dashboard/SKILL.md (referenced but not found - needs creation)
• MCP Config: .mcp-atlassian.json with atlassian-rovo server (PILOT status, Q2-Q3 2026)

Target State

• Data Sources: 1. Phase 1 (MVP): Excel exports (existing data, immediate value) 2. Phase 2 (Pilot): Atlassian Rovo MCP (real-time API access, Q2-Q3 2026)
• Visualization: Vizro dashboards with KPI cards, trend charts, tables
• Schema: 17-field normalized schema with validation
• Automation: Playwright E2E tests with screenshot evidence

Constraints

• MUST support Excel imports for immediate MVP delivery (no API dependency blocking)
• MUST NOT expose PII (assignee names) in shared reports (data privacy)
• MUST align with Dashboard-JSM.png mockup (KPI layout, chart types)
• MUST follow Local-First 3-tier testing strategy
• MAY integrate Atlassian Rovo MCP in Phase 2 (Q2-Q3 2026 pilot, not blocking MVP)

ITSM Dashboard Mockup Analysis

From Dashboard-JSM.png: - Top Row: 4 KPI cards (Total Tickets, Open Tickets, SLA Compliance %, Avg Resolution Time) - Second Row: 2 trend charts (Tickets by Status Over Time, Tickets by Priority) - Third Row: 2 bar charts (Top 5 Services, Tickets by Assignee) - Bottom Row: Data table with filters (sortable, searchable, paginated) - Controls: Date range filter, project filter (Azure/AWS/All), status filter

Decision

Adopt a 2-phase hybrid architecture: Excel-first MVP (immediate value) → MCP integration (pilot in Q2-Q3 2026).

Architecture Pattern: Phased Hybrid Integration

┌─────────────────────────────────────────────────────────────────────────┐
│                    ITSM DASHBOARD ARCHITECTURE (2-PHASE)                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────┐     │
│  │              PHASE 1: MVP (Excel Ground Truth)                 │     │
│  │  Timeline: Sprint 6 (2026-01-24 to 2026-02-07)                │     │
│  └─────────────────────────┬─────────────────────────────────────┘     │
│                            │                                            │
│  ┌─────────────────────────▼─────────────────────────────────┐         │
│  │         DATA INGESTION LAYER (Excel → JSON)              │         │
│  │                                                           │         │
│  │  ┌──────────────┐          ┌──────────────┐             │         │
│  │  │ Azure-Tickets│          │ AWS-Tickets  │             │         │
│  │  │   .xlsx      │          │   .xlsx      │             │         │
│  │  │ (541 tickets)│          │ (2,458 tix)  │             │         │
│  │  └──────┬───────┘          └──────┬───────┘             │         │
│  │         │                         │                     │         │
│  │         └─────────┬───────────────┘                     │         │
│  │                   │                                     │         │
│  │         ┌─────────▼─────────┐                           │         │
│  │         │  Excel Loader     │                           │         │
│  │         │  (pandas/openpyxl)│                           │         │
│  │         └─────────┬─────────┘                           │         │
│  │                   │                                     │         │
│  │         ┌─────────▼─────────┐                           │         │
│  │         │  Schema Validator │                           │         │
│  │         │  (Pydantic model) │                           │         │
│  │         └─────────┬─────────┘                           │         │
│  │                   │                                     │         │
│  │         ┌─────────▼─────────┐                           │         │
│  │         │ PII Masking       │                           │         │
│  │         │ (Assignee → ID)   │                           │         │
│  │         └─────────┬─────────┘                           │         │
│  │                   │                                     │         │
│  │         ┌─────────▼─────────┐                           │         │
│  │         │  JSON Export      │                           │         │
│  │         │  (normalized data)│                           │         │
│  │         └───────────────────┘                           │         │
│  └───────────────────────────────────────────────────────────┘         │
│                            │                                            │
│  ┌─────────────────────────▼─────────────────────────────────┐         │
│  │         VISUALIZATION LAYER (Vizro Dashboard)             │         │
│  │                                                           │         │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │         │
│  │  │  KPI Cards   │  │ Trend Charts │  │  Bar Charts  │   │         │
│  │  │              │  │              │  │              │   │         │
│  │  │ • Total Tix  │  │ • Status/Time│  │ • Top Services│   │         │
│  │  │ • Open Tix   │  │ • Priority   │  │ • Assignees  │   │         │
│  │  │ • SLA %      │  │              │  │              │   │         │
│  │  │ • Avg Resolve│  │              │  │              │   │         │
│  │  └──────────────┘  └──────────────┘  └──────────────┘   │         │
│  │                                                           │         │
│  │  ┌──────────────────────────────────────────────────────┐│         │
│  │  │           Data Table (Sortable, Filterable)          ││         │
│  │  │  Columns: ID, Status, Priority, Created, Resolved... ││         │
│  │  └──────────────────────────────────────────────────────┘│         │
│  │                                                           │         │
│  │  ┌──────────────────────────────────────────────────────┐│         │
│  │  │           Vizro Core Engine                          ││         │
│  │  │  (Plotly + Dash + Pydantic + McKinsey Visual Vocab)  ││         │
│  │  └──────────────────────────────────────────────────────┘│         │
│  └───────────────────────────────────────────────────────────┘         │
│                            │                                            │
│  ┌─────────────────────────▼─────────────────────────────────┐         │
│  │              EVIDENCE LAYER (Playwright)                   │         │
│  │  - Screenshots: tmp/evidence/itsm-dashboard-*.png         │         │
│  │  - JSON Data: tmp/evidence/itsm-dashboard-data.json       │         │
│  │  - HTML Export: tmp/evidence/itsm-dashboard.html          │         │
│  └────────────────────────────────────────────────────────────┘         │
│                                                                         │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────┐     │
│  │              PHASE 2: MCP INTEGRATION (Q2-Q3 2026 PILOT)       │     │
│  │  Timeline: Post-Sprint 6, depends on Rovo MCP pilot success   │     │
│  └─────────────────────────┬─────────────────────────────────────┘     │
│                            │                                            │
│  ┌─────────────────────────▼─────────────────────────────────┐         │
│  │         DATA INGESTION LAYER (MCP → JSON)                 │         │
│  │                                                           │         │
│  │  ┌──────────────────────────────────────────────────────┐│         │
│  │  │  Atlassian Rovo MCP (SSE Transport)                  ││         │
│  │  │  URL: https://mcp.atlassian.com/v1/sse              ││         │
│  │  │  Auth: ATLASSIAN_API_TOKEN (OAuth 2.1)              ││         │
│  │  └──────────────────────┬───────────────────────────────┘│         │
│  │                         │                                │         │
│  │  ┌──────────────────────▼───────────────────────────────┐│         │
│  │  │  MCP Capabilities:                                   ││         │
│  │  │  - jira.issues.search (JQL query)                    ││         │
│  │  │  - jira.issues.read (ticket details)                 ││         │
│  │  │  - jira.projects.read (project metadata)             ││         │
│  │  └──────────────────────┬───────────────────────────────┘│         │
│  │                         │                                │         │
│  │  ┌──────────────────────▼───────────────────────────────┐│         │
│  │  │  Real-Time Data Pipeline:                            ││         │
│  │  │  1. JQL Query → Filter by project (AWS/Azure)        ││         │
│  │  │  2. Rate Limit: 60 req/min (IBM Gateway Pattern)     ││         │
│  │  │  3. Schema Transform → Pydantic model                ││         │
│  │  │  4. PII Masking → Assignee ID                        ││         │
│  │  │  5. JSON Export → Same format as Excel pipeline      ││         │
│  │  └───────────────────────────────────────────────────────┘│         │
│  └───────────────────────────────────────────────────────────┘         │
│                            │                                            │
│  ┌─────────────────────────▼─────────────────────────────────┐         │
│  │         DUAL-SOURCE VALIDATION (Cross-Validation)          │         │
│  │  - Compare Excel data vs MCP data (agreement ≥95%)        │         │
│  │  - Detect discrepancies (ticket count, status, SLA)       │         │
│  │  - Evidence: tmp/evidence/itsm-cross-validation.json      │         │
│  └────────────────────────────────────────────────────────────┘         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

17-Field ITSM Schema (Pydantic Model)

from pydantic import BaseModel, Field
from datetime import datetime
from enum import Enum
from typing import Optional

class IssueType(str, Enum):
    INCIDENT = "Incident"
    SERVICE_REQUEST = "Service Request"
    PROBLEM = "Problem"
    CHANGE = "Change"

class Priority(str, Enum):
    P1_CRITICAL = "P1-Critical"
    P2_HIGH = "P2-High"
    P3_MEDIUM = "P3-Medium"
    P4_LOW = "P4-Low"

class Status(str, Enum):
    OPEN = "Open"
    IN_PROGRESS = "In Progress"
    RESOLVED = "Resolved"
    CLOSED = "Closed"
    WAITING_FOR_CUSTOMER = "Waiting for Customer"

class ITSMTicket(BaseModel):
    """17-field normalized ITSM ticket schema"""

    # Core identifiers
    ticket_id: str = Field(..., description="Jira ticket ID (e.g., AWS-1234)")
    project: str = Field(..., description="Project key (AWS or Azure)")

    # Ticket classification
    issue_type: IssueType
    priority: Priority
    status: Status

    # Assignee (PII-masked in shared reports)
    assignee_id: str = Field(..., description="Masked assignee ID (not name)")
    assignee_name: Optional[str] = Field(None, description="Real name (internal only)")

    # Service context
    service: str = Field(..., description="Affected service/component")
    summary: str = Field(..., description="Ticket summary")

    # Timestamps
    created_at: datetime
    resolved_at: Optional[datetime] = None
    closed_at: Optional[datetime] = None

    # SLA metrics
    sla_target_hours: int = Field(..., description="SLA target (hours)")
    sla_met: bool = Field(..., description="SLA compliance flag")
    resolution_hours: Optional[float] = Field(None, description="Actual resolution time")

    # Customer context
    customer_org: str = Field(..., description="Customer organization")
    severity: Optional[int] = Field(None, ge=1, le=5, description="Severity rating 1-5")

File Structure

Cloud-Infrastructure/
├── dashboards/
│   └── itsm/
│       ├── architecture/
│       │   ├── Dashboard-JSM.png (mockup reference)
│       │   ├── Azure-Tickets.xlsx (ground truth, 541 tickets)
│       │   └── AWS-Tickets.xlsx (ground truth, 2,458 tickets)
│       ├── config/
│       │   ├── dashboard-itsm.yaml (Vizro configuration)
│       │   └── schema.py (Pydantic model - 17 fields)
│       ├── data_sources/
│       │   ├── excel_loader.py (Phase 1: Excel → JSON)
│       │   └── mcp_loader.py (Phase 2: Rovo MCP → JSON)
│       ├── components/
│       │   ├── kpi_cards.py (Total, Open, SLA%, Avg Resolve)
│       │   ├── trend_charts.py (Status/Time, Priority)
│       │   ├── bar_charts.py (Top Services, Assignees)
│       │   └── data_table.py (Sortable, filterable table)
│       ├── validation/
│       │   ├── cross_validator.py (Excel vs MCP comparison)
│       │   └── pii_masker.py (Assignee name → ID)
│       ├── app.py (Vizro dashboard entry point)
│       ├── Dockerfile (containerized dashboard)
│       └── docker-compose.yml (Local-First development)
├── .mcp-atlassian.json (Rovo MCP config, PILOT status)
└── tmp/cloud-infrastructure/itsm/
    ├── evidence/
    │   ├── itsm-dashboard-*.png (Playwright screenshots)
    │   ├── itsm-dashboard-data.json (normalized data)
    │   └── itsm-cross-validation.json (Phase 2: Excel vs MCP)
    └── data/
        ├── azure-tickets-normalized.json (Phase 1 output)
        └── aws-tickets-normalized.json (Phase 1 output)

Consequences

Positive

• Immediate Value: Phase 1 delivers MVP using existing Excel data (no API blocking)
• Data Privacy: PII masking ensures assignee names not exposed in shared reports
• Mockup Alignment: Vizro dashboard matches Dashboard-JSM.png layout
• Future-Proof: Phase 2 MCP integration path defined (not blocking MVP)
• Dual-Source Validation: Excel ground truth enables cross-validation of MCP data (≥95% agreement)
• Reusable Pattern: Excel → JSON pipeline reusable for other Jira exports

Negative

• Manual Export: Phase 1 requires manual Excel export workflow (not real-time)
• Data Staleness: Excel data is point-in-time snapshot (not live updates)
• Dual Maintenance: Need to maintain both Excel and MCP data loaders (Phase 2)
• MCP Dependency: Phase 2 requires Atlassian Rovo MCP pilot success (Q2-Q3 2026)
• SSE Transport: Rovo MCP uses deprecated SSE (migration to Streamable HTTP required by Q3 2026)

Risks

Risk	Probability	Impact	Mitigation
Excel Schema Drift	Medium	Medium	Validate schema on every import; Fail fast if fields missing
PII Leak	Low	High	Enforce PII masking in data loader; Playwright tests verify no names in screenshots
Rovo MCP Pilot Failure	Medium	Low	Phase 1 Excel pipeline remains fallback; No MVP blocking
SSE Deprecation	High	Medium	Monitor Atlassian migration timeline; Plan HTTP transport upgrade by Q3 2026
Rate Limit Exceeded	Low	Low	IBM Gateway Pattern enforces 60 req/min; Cache responses; Batch queries
Data Volume	Low	Medium	2,999 tickets (541+2,458) manageable; Paginate table; Filter by date range

Alternatives Considered

Alternative 1: Direct Jira REST API

• Rejected: No MCP integration; Requires custom authentication; Less ADLC-aligned
• Benefit: Well-documented API; No pilot dependency
• Trade-off: No Claude-native integration; Manual API client development; Higher maintenance

Alternative 2: Jira Data Center Export API

• Rejected: Enterprise feature (not available in Cloud); Overkill for 3k tickets
• Benefit: Bulk export capabilities; Automated scheduling
• Trade-off: Licensing cost; Not applicable to Cloud instances

Alternative 3: Real-Time MCP Only (No Excel)

• Rejected: Blocks MVP on Rovo MCP pilot (Q2-Q3 2026); High risk
• Benefit: Single data source; Always current data
• Trade-off: No immediate value; Pilot dependency; Excel ground truth lost

Alternative 4: CSV Export (Not Excel)

• Rejected: Excel already provided; CSV loses metadata (formulas, types)
• Benefit: Simpler parsing (csv.DictReader)
• Trade-off: Need to regenerate exports; Excel more robust for date/currency types

References

• Atlassian Rovo MCP Documentation
• Vizro Documentation
• ADLC Constitution Principle VI: Governance
• Analytics Dashboard Skill
• Dashboard Mockup

Evidence

• Architecture diagram: tmp/cloud-infrastructure/architecture-decisions/ADR-005-diagram.txt (this file - ASCII art)
• Mockup reference: dashboards/itsm/architecture/Dashboard-JSM.png (validated)
• Ground truth data: dashboards/itsm/architecture/{Azure|AWS}-Tickets.xlsx (541 + 2,458 tickets)
• MCP config: .mcp-atlassian.json (PILOT status, rate limit 60 req/min)
• Schema: 17-field Pydantic model (defined in this ADR)
• Cross-validation target: ≥95% (Excel vs MCP agreement in Phase 2)

Approval

• cloud-architect: Approved (92% agreement score)
• product-owner: Pending coordination evidence
• HITL/Manager: Pending production deployment approval
• security-compliance-engineer: Pending PII masking validation

---

Version: 1.0.0 Constitutional Checkpoint: CHK049 (Agentic behavior specification), CHK050 (SOPs defined), CHK033 (Data privacy) Next Phase: Build Phase (Excel loader + Vizro YAML configuration) Phase 2 Trigger: Atlassian Rovo MCP pilot success (Q2-Q3 2026)