Use Case 011: Dashboard and Metrics Visualization

Overview

Property Value
Use Case ID UC-011
Use Case Name Dashboard and Metrics Visualization
Module Monitoring and Analytics - System Dashboard
Priority Medium
Status Implemented
Version 1.0
Last Updated January 30, 2026

Description

This use case describes the administrative dashboard that displays real-time system metrics, health indicators, and activity monitoring for the Riptide Application Manager platform. Administrators can view key performance indicators, track system status, analyze trends, and quickly navigate to management modules. The dashboard provides auto-refreshing data, exportable reports, historical analysis with date range filtering, and a responsive design for mobile viewing.

Actors

Actor Description Role
Administrator System administrator monitoring platform health and activity Primary
System Application Manager platform generating metrics Supporting
Database Identity and operational databases providing metric data Supporting
Cache Service Redis or in-memory cache for performance optimization Supporting
External Services Email service, external APIs being monitored Supporting

Preconditions

  1. Administrator is authenticated and has dashboard access permissions
  2. Application Manager platform is running
  3. Metric collection services are operational
  4. Database connections are established
  5. Cache service is available (optional but recommended)
  6. At least one Riptide application is registered in the system

Postconditions

Success Postconditions

  1. Dashboard loads with current metrics and status indicators
  2. Real-time data refreshes according to configured interval
  3. Activity feed displays recent system events
  4. Health indicators reflect accurate system status
  5. User interactions (filters, exports) are logged
  6. Session metrics updated (last dashboard view timestamp)

Failure Postconditions

  1. Graceful degradation if some metrics unavailable
  2. Cached data displayed with staleness indicator
  3. Error messages shown for unavailable components
  4. Partial dashboard rendered if some services are down
  5. Retry mechanisms activated for transient failures

Triggers

  • Administrator logs into Application Manager
  • Administrator navigates to /dashboard route
  • Auto-refresh timer expires
  • Administrator manually clicks refresh button
  • Administrator applies date range filter or exports data

Basic Flow (Happy Path)

sequenceDiagram actor Admin as Administrator participant Web as Web UI participant API as Dashboard API participant Cache as Cache Service participant DB as Database participant Email as Email Service participant Apps as Riptide Apps Admin->>Web: Login and navigate to dashboard Web->>API: GET /api/v1/dashboard/metrics API->>Cache: Check for cached metrics Cache->>API: Cache miss or expired par Parallel Metric Collection API->>DB: Query active trial users count API->>DB: Query active sessions count API->>DB: Query total roles count API->>DB: Query recent registrations API->>DB: Query recent logins API->>DB: Query configuration changes API->>DB: Query application statistics API->>DB: Test database connection (health check) API->>Email: Test email service connectivity API->>Apps: Measure API response times end DB-->>API: Trial users: 127 (↑ 12% from yesterday) DB-->>API: Active sessions: 43 (↓ 5% from yesterday) DB-->>API: Total roles: 85 (no change) DB-->>API: Recent activities (last 50 events) DB-->>API: Application stats DB-->>API: Database: Healthy (Response: 15ms) Email-->>API: Email service: Healthy (Response: 230ms) Apps-->>API: API avg response time: 145ms API->>API: Calculate trend indicators API->>API: Calculate percentage changes API->>API: Format dashboard payload API->>Cache: Store metrics (TTL: 30 seconds) API->>Web: 200 OK (dashboard data) Web->>Admin: Render dashboard with metrics Note over Web,Admin: Dashboard displays:<br/>- Metric cards with trends<br/>- Health status indicators<br/>- Activity feed<br/>- Quick action buttons loop Auto-refresh every 30 seconds Web->>API: GET /api/v1/dashboard/metrics API->>Cache: Check cache Cache->>API: Return cached data API->>Web: 200 OK (cached metrics) Web->>Admin: Update dashboard (smooth transition) end Admin->>Web: Click "Trial Users" metric card Web->>Admin: Navigate to trial user management

Detailed Steps

  1. Administrator Accesses Dashboard

    • Administrator successfully authenticates
    • System verifies dashboard access permissions
    • Web UI routes to /dashboard endpoint
    • Loading indicator displayed during data fetch

  2. System Collects Real-Time Metrics

    • Check cache for recent metrics (last 30 seconds)
    • If cache miss or expired, query databases in parallel:
      • Count active trial users (IsActive = true, not expired)
      • Count active sessions (created in last 24 hours)
      • Count total roles across all applications
      • Retrieve recent user registrations (last 10)
      • Retrieve recent login events (last 10)
      • Retrieve recent configuration changes (last 10)
      • Calculate application usage statistics

  3. System Performs Health Checks

    • Test database connectivity and measure response time
    • Test email service connectivity (SMTP hello or SES test)
    • Measure average API response times (last 100 requests)
    • Check cache service availability
    • Validate external dependency health

  4. System Calculates Trends

    • Compare current metrics with previous period (24 hours ago)
    • Calculate percentage change for each metric
    • Determine trend direction (up, down, no change)
    • Apply business logic for trend indicators:
      • Green (positive): Increased registrations, decreased errors
      • Red (negative): Decreased activity, increased failures
      • Gray (neutral): No significant change

  5. System Composes Dashboard Payload

    • Structure metric cards with values, trends, and icons
    • Format health indicators with status and response times
    • Build activity feed with timestamps and descriptions
    • Include quick action buttons with navigation links
    • Add metadata (last updated timestamp, refresh interval)

  6. System Caches Response

    • Store complete dashboard payload in cache
    • Set TTL (time-to-live) to 30 seconds
    • Tag cache entry with timestamp for staleness detection

  7. Web UI Renders Dashboard

    • Display metric cards in grid layout
    • Render health status indicators with colors
    • Populate activity feed with scrollable list
    • Show quick action buttons
    • Display last updated timestamp
    • Initialize auto-refresh timer (30 seconds)

  8. Auto-Refresh Cycle Begins

    • Timer triggers refresh request every 30 seconds
    • API returns cached data (fast response)
    • UI updates smoothly without full page reload
    • Animations highlight changed values

  9. Administrator Interacts with Dashboard

    • Click metric cards to navigate to detailed views
    • Use quick action buttons for common tasks
    • Apply date range filter for historical analysis
    • Export metrics to CSV or Excel format
    • Manually refresh if needed

Alternative Flows

Alt Flow 1: Database Connectivity Issue

sequenceDiagram actor Admin as Administrator participant Web as Web UI participant API as Dashboard API participant Cache as Cache Service participant DB as Database Admin->>Web: Access dashboard Web->>API: GET /api/v1/dashboard/metrics API->>Cache: Check cache Cache->>API: Cache expired API->>DB: Query metrics DB--xAPI: Connection timeout / Error alt Cache has stale data API->>Cache: Retrieve stale cached data Cache->>API: Return stale metrics API->>API: Add staleness indicator API->>Web: 200 OK (stale data with warning) Web->>Admin: Show dashboard with warning banner Note over Admin,Web: "⚠️ Displaying cached data.<br/>Database connection issues detected." else No cache available API->>API: Return partial metrics (defaults) API->>Web: 206 Partial Content (degraded) Web->>Admin: Show dashboard with error indicators Note over Admin,Web: "❌ Some metrics unavailable.<br/>System health check failed." end API->>API: Log database connectivity error API->>API: Trigger alert to DevOps team

Steps:

  1. Dashboard API attempts to query database
  2. Database connection fails or times out
  3. System checks cache for stale data:
    • If available: Return cached data with staleness warning
    • If not available: Return partial metrics with default values
  4. Display warning banner: "⚠️ Displaying cached data. Database connection issues detected."
  5. Health indicator shows database status as "Unhealthy"
  6. Log error with full context (timestamp, error message, stack trace)
  7. Send alert to operations team
  8. Administrator can click "Retry" button to force refresh

Alt Flow 2: Email Service Health Check Failure

flowchart TD A[Dashboard loads] --> B{Test email service} B -->|Connection timeout| C[Email service: Unhealthy] B -->|Authentication failure| D[Email service: Degraded] B -->|Connection success| E[Email service: Healthy] C --> F[Display red status indicator] D --> G[Display yellow status indicator] E --> H[Display green status indicator] F --> I[Show error details in tooltip] G --> J[Show warning details in tooltip] H --> K[Show response time in tooltip] I --> L[Metrics still displayed normally] J --> L K --> L L --> M[Admin can navigate to email config]

Steps:

  1. Health check attempts to connect to email service
  2. Connection fails (timeout, authentication error, service unavailable)
  3. Email service status indicator shows:
    • Red (Unhealthy): Cannot connect, emails will not be sent
    • Yellow (Degraded): Connected but slow response time (> 1 second)
    • Green (Healthy): Connected, response time < 500ms
  4. Tooltip displays error details: "Connection timeout after 5 seconds"
  5. Dashboard continues to display other metrics normally
  6. Administrator can click status indicator to view email service configuration
  7. System logs email service health check failure
  8. Monitoring alert triggered if failure persists > 5 minutes

Alt Flow 3: Cache Service Unavailable

sequenceDiagram actor Admin as Administrator participant API as Dashboard API participant Cache as Cache Service participant DB as Database Admin->>API: GET /api/v1/dashboard/metrics API->>Cache: Check cache Cache--xAPI: Connection refused Note over API: Cache unavailable - fall back to direct DB queries API->>DB: Query all metrics (uncached) DB->>API: Return fresh data API->>API: Process metrics (slower) API->>Admin: 200 OK (slower response time) Note over API,Admin: Response time: 800ms (vs 50ms cached) API->>API: Log cache unavailability warning API->>API: Continue without caching API->>API: Alert DevOps if cache down > 5 minutes

Steps:

  1. Dashboard API attempts to connect to cache service
  2. Cache service is unavailable (Redis down, network issue)
  3. API logs warning: "Cache service unavailable, falling back to database"
  4. API queries database directly for all metrics (bypasses cache)
  5. Response time increases (800ms vs 50ms with cache)
  6. Dashboard loads successfully but slower
  7. Auto-refresh continues to work (directly hitting database)
  8. System monitoring detects degraded performance
  9. Alert sent to DevOps if cache unavailable > 5 minutes
  10. Administrator sees normal dashboard but may notice slower loading

Alt Flow 4: Historical Data Export

sequenceDiagram actor Admin as Administrator participant Web as Web UI participant API as Export API participant DB as Database participant Job as Background Job Admin->>Web: Click "Export Metrics" Web->>Admin: Show export dialog Admin->>Web: Select date range (Jan 1-30, 2026) Admin->>Web: Select format (CSV/Excel) Admin->>Web: Select metrics to include Web->>API: POST /api/v1/dashboard/export API->>API: Validate date range (max 1 year) API->>API: Estimate data size alt Small dataset (< 10,000 rows) API->>DB: Query historical metrics DB->>API: Return data API->>API: Generate CSV/Excel file API->>Web: Return file download Web->>Admin: Download file to browser else Large dataset (> 10,000 rows) API->>Job: Queue background export job Job->>DB: Query data in batches Job->>Job: Generate file incrementally Job->>Job: Upload to temporary storage API->>Web: 202 Accepted (job queued) Web->>Admin: "Export in progress. You'll receive email when ready." Note over Job,Admin: Background processing Job->>Admin: Email with download link (expires in 24 hours) end

Steps:

  1. Administrator clicks "Export" button on dashboard
  2. Export dialog opens with options:
    • Date range selector (start date, end date)
    • Format: CSV or Excel
    • Metrics: Select all or specific metrics
    • Include trend data: Yes/No
  3. Administrator selects options and submits
  4. System validates:
    • Date range not more than 1 year
    • Start date before end date
    • At least one metric selected
  5. System estimates data size:
    • Small (<10,000 rows): Generate immediately
    • Large (>10,000 rows): Queue background job
  6. For immediate export:
    • Query database for historical data
    • Generate CSV or Excel file in memory
    • Return file download (Content-Type: application/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)
  7. For background export:
    • Create export job record
    • Return 202 Accepted with job ID
    • Process in background worker
    • Send email with download link when complete
    • Expire link after 24 hours

Alt Flow 5: Mobile Responsive View

Steps:

  1. Administrator accesses dashboard from mobile device (viewport < 768px)
  2. Web UI detects screen size and applies responsive layout:
    • Metric cards stack vertically (1 column instead of 3-4)
    • Charts resize to fit narrow screen
    • Activity feed shows abbreviated entries
    • Navigation menu collapses to hamburger icon
    • Quick action buttons stack vertically
    • Health indicators remain visible but condensed
  3. Touch gestures enabled:
    • Swipe to refresh dashboard
    • Tap metric cards to navigate
    • Pinch to zoom on charts
  4. Auto-refresh continues to function (preserve battery)
  5. Export functionality available but optimized for mobile
  6. Dashboard remains fully functional on mobile devices

Business Rules

Rule ID Description Enforcement
BR-001 Dashboard metrics cached for 30 seconds to optimize performance Cache service TTL configuration
BR-002 Auto-refresh interval is 30 seconds (configurable 10-300 seconds) Client-side timer + API configuration
BR-003 Trend indicators compare current value vs 24 hours ago Metric calculation logic
BR-004 Activity feed displays maximum 50 most recent events Database query LIMIT clause
BR-005 Health check timeout is 5 seconds per service API timeout configuration
BR-006 Export date range limited to maximum 1 year API validation logic
BR-007 Large exports (>10,000 rows) processed asynchronously Background job threshold
BR-008 Export download links expire after 24 hours File storage cleanup job
BR-009 Dashboard requires "Administrator" or "Dashboard Viewer" role Authorization middleware
BR-010 Stale cached data displayed if database unavailable (max 5 minutes) Cache staleness tolerance

Data Requirements

Dashboard Metrics Payload

{
  "timestamp": "2026-01-30T14:35:22Z",
  "refreshInterval": 30,
  "metrics": {
    "activeTrialUsers": {
      "value": 127,
      "trend": "up",
      "change": "+12%",
      "previousValue": 113,
      "comparisonPeriod": "24h"
    },
    "activeSessions": {
      "value": 43,
      "trend": "down",
      "change": "-5%",
      "previousValue": 45,
      "comparisonPeriod": "24h"
    },
    "totalRoles": {
      "value": 85,
      "trend": "neutral",
      "change": "0%",
      "previousValue": 85,
      "comparisonPeriod": "24h"
    },
    "totalApplications": {
      "value": 12,
      "trend": "up",
      "change": "+1",
      "previousValue": 11,
      "comparisonPeriod": "24h"
    }
  },
  "healthIndicators": {
    "database": {
      "status": "healthy",
      "responseTime": 15,
      "unit": "ms",
      "lastChecked": "2026-01-30T14:35:22Z"
    },
    "emailService": {
      "status": "healthy",
      "responseTime": 230,
      "unit": "ms",
      "lastChecked": "2026-01-30T14:35:22Z"
    },
    "apiAverage": {
      "status": "healthy",
      "responseTime": 145,
      "unit": "ms",
      "sampleSize": 100
    },
    "cacheService": {
      "status": "healthy",
      "responseTime": 3,
      "unit": "ms",
      "lastChecked": "2026-01-30T14:35:22Z"
    }
  },
  "recentActivity": [
    {
      "id": "act-001",
      "type": "user_registration",
      "description": "New trial user registered: jane.doe@example.com",
      "timestamp": "2026-01-30T14:30:15Z",
      "actor": "System",
      "severity": "info"
    },
    {
      "id": "act-002",
      "type": "user_login",
      "description": "Trial user logged in: john.smith@example.com",
      "timestamp": "2026-01-30T14:28:42Z",
      "actor": "john.smith@example.com",
      "severity": "info"
    },
    {
      "id": "act-003",
      "type": "config_change",
      "description": "Application 'Fee Manager' configuration updated",
      "timestamp": "2026-01-30T14:20:11Z",
      "actor": "admin@riptide.com",
      "severity": "warning"
    }
  ],
  "quickActions": [
    {
      "id": "qa-001",
      "label": "Manage Trial Users",
      "icon": "users",
      "route": "/trial-users",
      "enabled": true
    },
    {
      "id": "qa-002",
      "label": "View Active Sessions",
      "icon": "activity",
      "route": "/sessions",
      "enabled": true
    },
    {
      "id": "qa-003",
      "label": "Configure Applications",
      "icon": "settings",
      "route": "/applications",
      "enabled": true
    },
    {
      "id": "qa-004",
      "label": "Manage Roles",
      "icon": "shield",
      "route": "/roles",
      "enabled": true
    }
  ]
}

Historical Metrics Record

{
  "id": "uuid-v4",
  "metricType": "active_trial_users",
  "value": 127,
  "timestamp": "2026-01-30T14:00:00Z",
  "metadata": {
    "breakdown": {
      "newThisWeek": 18,
      "expiringThisWeek": 6
    }
  }
}

Export Job Record

{
  "id": "uuid-v4",
  "userId": "admin-user-id",
  "format": "csv",
  "dateRange": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-30T23:59:59Z"
  },
  "metricsIncluded": ["activeTrialUsers", "activeSessions", "totalRoles"],
  "status": "processing",
  "createdAt": "2026-01-30T14:35:00Z",
  "completedAt": null,
  "downloadUrl": null,
  "expiresAt": null,
  "rowCount": null,
  "fileSizeBytes": null
}

User Interface

Dashboard Layout (Desktop)

┌──────────────────────────────────────────────────────────────────────────┐
│  Riptide Application Manager          [🔔 Notifications]  [Admin ▼]     │
├──────────────────────────────────────────────────────────────────────────┤
│  📊 Dashboard                                    Last Updated: Just now  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│                                                                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │
│  │ 👥 Trial Users  │  │ ⚡ Active       │  │ 🔐 Total Roles  │        │
│  │                 │  │    Sessions     │  │                 │        │
│  │      127        │  │       43        │  │       85        │        │
│  │   ↑ +12%        │  │   ↓ -5%         │  │   → 0%          │        │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘        │
│                                                                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │
│  │ 📱 Applications │  │ 📧 Email Queue  │  │ ⚠️  Alerts       │        │
│  │                 │  │                 │  │                 │        │
│  │       12        │  │        3        │  │        0        │        │
│  │   ↑ +1          │  │   → pending     │  │   🟢 All Clear  │        │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘        │
│                                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐ │
│  │ System Health                                    🔄 Refresh        │ │
│  │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │ │
│  │                                                                   │ │
│  │  🟢 Database           Healthy     (15ms)                        │ │
│  │  🟢 Email Service      Healthy     (230ms)                       │ │
│  │  🟢 API Average        Healthy     (145ms)                       │ │
│  │  🟢 Cache Service      Healthy     (3ms)                         │ │
│  │                                                                   │ │
│  └───────────────────────────────────────────────────────────────────┘ │
│                                                                          │
│  ┌───────────────────────────────────┐  ┌──────────────────────────┐   │
│  │ Recent Activity          [Export] │  │ Quick Actions            │   │
│  │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │  │ ━━━━━━━━━━━━━━━━━━━━━  │   │
│  │                                   │  │                          │   │
│  │ 🆕 2 min ago                      │  │ [👥 Manage Trial Users] │   │
│  │ New trial user registered:        │  │                          │   │
│  │ jane.doe@example.com              │  │ [⚡ View Active Sessions]│   │
│  │                                   │  │                          │   │
│  │ 🔓 4 min ago                      │  │ [⚙️  Configure Apps]     │   │
│  │ Trial user logged in:             │  │                          │   │
│  │ john.smith@example.com            │  │ [🔐 Manage Roles]       │   │
│  │                                   │  │                          │   │
│  │ ⚙️  12 min ago                     │  │ [📊 View Reports]       │   │
│  │ Configuration updated:            │  │                          │   │
│  │ Fee Manager                       │  │ [📧 Email Settings]     │   │
│  │                                   │  │                          │   │
│  │ 🆕 18 min ago                     │  └──────────────────────────┘   │
│  │ New trial user registered:        │                               │
│  │ bob.jones@example.com             │  [📅 Jan 1 - Jan 30, 2026]   │
│  │                                   │  [📥 Export Dashboard]        │
│  │ [Show More...]                    │                               │
│  └───────────────────────────────────┘                               │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Dashboard Layout (Mobile)

┌────────────────────────────────────┐
│  ≡  Dashboard        [Admin ▼]     │
├────────────────────────────────────┤
│  Last Updated: Just now  🔄        │
│                                    │
│  ┌──────────────────────────────┐ │
│  │ 👥 Trial Users               │ │
│  │         127                  │ │
│  │      ↑ +12%                  │ │
│  └──────────────────────────────┘ │
│                                    │
│  ┌──────────────────────────────┐ │
│  │ ⚡ Active Sessions            │ │
│  │          43                  │ │
│  │      ↓ -5%                   │ │
│  └──────────────────────────────┘ │
│                                    │
│  ┌──────────────────────────────┐ │
│  │ 🔐 Total Roles               │ │
│  │          85                  │ │
│  │      → 0%                    │ │
│  └──────────────────────────────┘ │
│                                    │
│  ┌──────────────────────────────┐ │
│  │ System Health      [Details] │ │
│  │ ━━━━━━━━━━━━━━━━━━━━━━━━━  │ │
│  │ 🟢 All Systems Operational   │ │
│  └──────────────────────────────┘ │
│                                    │
│  ┌──────────────────────────────┐ │
│  │ Recent Activity              │ │
│  │ ━━━━━━━━━━━━━━━━━━━━━━━━━  │ │
│  │ 🆕 New registration (2m ago) │ │
│  │ 🔓 User login (4m ago)       │ │
│  │ ⚙️  Config update (12m ago)   │ │
│  │ [Show More...]               │ │
│  └──────────────────────────────┘ │
│                                    │
│  [👥 Manage Users]                │
│  [⚡ View Sessions]               │
│  [⚙️  Configure Apps]              │
│  [📊 View Reports]                │
│                                    │
└────────────────────────────────────┘

Export Dialog

┌─────────────────────────────────────────────┐
│  Export Dashboard Metrics                   │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│                                             │
│  Date Range                                 │
│  ┌───────────────┐  to  ┌───────────────┐  │
│  │ 01/01/2026    │      │ 01/30/2026    │  │
│  └───────────────┘      └───────────────┘  │
│                                             │
│  Format                                     │
│  ⦿ CSV                                      │
│  ○ Excel (XLSX)                             │
│                                             │
│  Metrics to Include                         │
│  ☑ Active Trial Users                       │
│  ☑ Active Sessions                          │
│  ☑ Total Roles                              │
│  ☑ Applications                             │
│  ☑ Recent Activity                          │
│  ☑ System Health Metrics                    │
│                                             │
│  Options                                    │
│  ☑ Include trend data                       │
│  ☑ Include timestamps                       │
│  ☐ Detailed breakdown                       │
│                                             │
│  Estimated rows: ~8,500                     │
│  Estimated size: 2.3 MB                     │
│                                             │
│  ┌─────────┐                                │
│  │  Export │  [Cancel]                      │
│  └─────────┘                                │
└─────────────────────────────────────────────┘

API Endpoints

Get Dashboard Metrics

Endpoint: GET /api/v1/dashboard/metrics

Authentication: Required (Administrator or Dashboard Viewer role)

Query Parameters:

?refresh=true           // Force cache bypass
&includeHistory=false   // Include historical comparison data

Success Response: 200 OK

{
  "timestamp": "2026-01-30T14:35:22Z",
  "refreshInterval": 30,
  "metrics": {
    "activeTrialUsers": {
      "value": 127,
      "trend": "up",
      "change": "+12%",
      "previousValue": 113,
      "comparisonPeriod": "24h"
    },
    "activeSessions": {
      "value": 43,
      "trend": "down",
      "change": "-5%",
      "previousValue": 45,
      "comparisonPeriod": "24h"
    }
  },
  "healthIndicators": {
    "database": {
      "status": "healthy",
      "responseTime": 15
    }
  },
  "recentActivity": [...],
  "quickActions": [...]
}

Error Response: 503 Service Unavailable

{
  "error": "ServiceUnavailable",
  "message": "Dashboard metrics temporarily unavailable",
  "details": "Database connection failed. Displaying cached data.",
  "cacheTimestamp": "2026-01-30T14:34:00Z",
  "staleData": true
}

Export Dashboard Metrics

Endpoint: POST /api/v1/dashboard/export

Authentication: Required (Administrator role)

Request Body:

{
  "format": "csv",
  "dateRange": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-30T23:59:59Z"
  },
  "metrics": [
    "activeTrialUsers",
    "activeSessions",
    "totalRoles"
  ],
  "includeTrends": true,
  "includeTimestamps": true
}

Success Response (Small Dataset): 200 OK

Content-Type: text/csv
Content-Disposition: attachment; filename="dashboard-metrics-2026-01-30.csv"

Timestamp,Active Trial Users,Active Sessions,Total Roles
2026-01-30 14:00:00,127,43,85
2026-01-30 13:00:00,125,45,85
...

Success Response (Large Dataset): 202 Accepted

{
  "jobId": "export-job-12345",
  "status": "processing",
  "message": "Export job queued. You'll receive an email when ready.",
  "estimatedRows": 15000,
  "estimatedCompletionTime": "2026-01-30T14:40:00Z"
}

Get Recent Activity

Endpoint: GET /api/v1/dashboard/activity

Authentication: Required (Administrator or Dashboard Viewer role)

Query Parameters:

?limit=50              // Number of events (default: 50, max: 200)
&since=2026-01-30T00:00:00Z  // Events after timestamp
&types=user_registration,user_login  // Filter by event types

Success Response: 200 OK

{
  "activities": [
    {
      "id": "act-001",
      "type": "user_registration",
      "description": "New trial user registered: jane.doe@example.com",
      "timestamp": "2026-01-30T14:30:15Z",
      "actor": "System",
      "severity": "info",
      "metadata": {
        "userId": "user-uuid",
        "email": "jane.doe@example.com"
      }
    }
  ],
  "total": 1247,
  "hasMore": true
}

Performance Requirements

Metric Target Critical Threshold
Dashboard initial load time < 1 second < 3 seconds
Cached metrics response time < 100ms < 500ms
Uncached metrics response time < 1.5 seconds < 5 seconds
Auto-refresh interval 30 seconds 10 seconds (min)
Health check timeout per service 3 seconds 5 seconds
Export generation (small dataset) < 5 seconds < 15 seconds
Export generation (large dataset) < 5 minutes < 15 minutes
Concurrent dashboard viewers supported 100 50
Metric calculation accuracy 100% 99%

Security Considerations

Access Control

  • Dashboard requires authentication
  • Role-based access: Administrator, Dashboard Viewer, or higher
  • Sensitive metrics (e.g., failed login attempts) visible only to Administrators
  • Activity feed respects data visibility rules (no PII for limited roles)
  • API endpoints protected by JWT authentication

Data Privacy

  • Personal identifiable information (PII) masked in activity feed for non-admin users
  • Email addresses displayed as "j***@example.com" for Dashboard Viewer role
  • Export files encrypted if containing sensitive data
  • Export download links use signed URLs with expiration
  • Activity logs do not include credentials or tokens

Performance Security

  • Cache poisoning prevention (validate data before caching)
  • Rate limiting on dashboard API (100 requests/minute per user)
  • Export rate limiting (5 exports per hour per user)
  • Prevent excessive auto-refresh (minimum 10-second interval)
  • Query timeout limits to prevent resource exhaustion

Audit Trail

  • All dashboard exports logged with timestamp and user
  • Filter/date range changes logged for compliance
  • Failed health checks logged and monitored
  • Abnormal metric patterns trigger alerts
  • Dashboard access tracked for security monitoring

Testing Scenarios

Test Case 1: Successful Dashboard Load

Given: Administrator authenticated, all services healthy
When: Administrator navigates to dashboard
Then: Dashboard loads within 1 second, all metrics displayed correctly
Verify: Metric values accurate, health indicators green, activity feed populated

Test Case 2: Auto-Refresh Functionality

Given: Dashboard loaded and displayed
When: 30 seconds elapse
Then: Dashboard auto-refreshes without page reload
Verify: Metrics update smoothly, no UI flicker, updated timestamp displayed

Test Case 3: Database Failure Graceful Degradation

Given: Dashboard loaded, database becomes unavailable
When: Auto-refresh triggers
Then: Cached data displayed with staleness warning
Verify: Dashboard still functional, warning banner visible, health indicator shows database unhealthy

Test Case 4: Export Small Dataset

Given: Administrator on dashboard, date range selected (1 week)
When: Administrator clicks "Export to CSV"
Then: CSV file downloads immediately
Verify: File contains correct data, formatted properly, all metrics included

Test Case 5: Export Large Dataset (Background Job)

Given: Administrator on dashboard, date range selected (1 year)
When: Administrator clicks "Export to Excel"
Then: 202 Accepted response, job queued message displayed
When: Background job completes
Then: Email sent with download link
Verify: Link works, file contains all data, link expires after 24 hours

Test Case 6: Mobile Responsive Layout

Given: Administrator accesses dashboard from mobile device (iPhone)
When: Dashboard loads
Then: Responsive layout displayed, metrics stack vertically
Verify: All features accessible, touch gestures work, auto-refresh functional

Test Case 7: Email Service Health Failure

Given: Email service is down
When: Dashboard loads
Then: Email service health indicator shows unhealthy (red)
Verify: Other metrics still displayed, tooltip shows error details, alert triggered

Test Case 8: Metric Trend Calculation

Given: Active trial users increased from 100 to 120 (20% increase)
When: Dashboard loads
Then: Trial users metric shows "120" with "↑ +20%" indicator
Verify: Trend direction correct, percentage accurate, comparison period displayed

Test Case 9: Cache Performance Optimization

Given: Dashboard accessed by 50 concurrent users
When: All users request metrics simultaneously
Then: All receive response within 100ms (from cache)
Verify: Database queries minimal (cached), no performance degradation

Test Case 10: Date Range Filter Validation

Given: Administrator attempts to export data
When: Administrator selects date range > 1 year
Then: Validation error displayed: "Date range cannot exceed 1 year"
Verify: Export blocked, user prompted to adjust range

Monitoring and Analytics

Key Metrics to Track

  • Dashboard Load Time: P50, P95, P99 response times
  • Cache Hit Rate: Percentage of requests served from cache
  • Auto-Refresh Success Rate: Successful refreshes / Total refresh attempts
  • Export Generation Time: Time to generate exports by size
  • Health Check Failures: Number of service health check failures per day
  • Concurrent Viewers: Number of users viewing dashboard simultaneously
  • Data Staleness: How often stale cached data is displayed
  • Mobile Usage: Percentage of dashboard views from mobile devices

Alerts

  • Dashboard load time > 3 seconds for 5 consecutive requests
  • Health check failure rate > 10% in 5 minutes
  • Cache service unavailable for > 5 minutes
  • Database connectivity issues detected
  • Export job failures > 20% in 1 hour
  • Abnormal spike in metric values (potential data quality issue)
  • Dashboard API error rate > 5% in 10 minutes

Dashboard Usage Analytics

  • Most viewed metric cards
  • Most frequently used quick action buttons
  • Average time spent on dashboard
  • Export frequency by format (CSV vs Excel)
  • Popular date ranges for exports
  • Activity feed scroll depth (how far users scroll)
  • UC-001: Trial User Self-Registration (metric: active trial users)
  • UC-002: Trial User Login and Session Management (metric: active sessions)
  • UC-005: Administrator Trial User Management (navigation target)
  • UC-006: Role and Permission Management (metric: total roles)
  • UC-008: Application Configuration and Registration (metric: total applications)
  • UC-009: System Health Monitoring and Alerting (health indicators)
  • UC-010: Audit Trail and Activity Logging (activity feed data source)
  • UC-012: Reporting and Analytics (export functionality)

Notes and Assumptions

  1. Real-Time Definition: "Real-time" metrics are cached for 30 seconds for performance; truly instant data not required
  2. Historical Data Storage: Metrics stored hourly in database for historical analysis; daily aggregates kept indefinitely
  3. Cache Technology: Redis preferred for caching; in-memory cache acceptable for smaller deployments
  4. Mobile Optimization: Dashboard fully functional on mobile but optimized for desktop viewing
  5. Export Size Limits: Exports > 1 million rows not supported; users directed to use data warehouse for large-scale analysis
  6. Metric Accuracy: Metrics are eventually consistent; slight delays acceptable during high load
  7. Customization: Dashboard layout and metrics are fixed; custom dashboards not currently supported (future enhancement)
  8. Time Zones: All timestamps displayed in user's local time zone; stored in UTC in database
  9. Browser Support: Modern browsers only (Chrome, Firefox, Safari, Edge); IE 11 not supported

Revision History

Version Date Author Changes
1.0 2026-01-30 System Analyst Initial use case documentation

Document Owner: Platform Architecture Team
Stakeholders: Product Management, Engineering, Operations, Customer Success
Review Cycle: Quarterly or as needed for major changes