# Dashboard Data Flow

## Overview

The Dashboard Data Flow describes how StellaOps aggregates security posture data from multiple sources and presents it to users through the Console UI. The dashboard provides real-time visibility into vulnerability counts, policy compliance, scan status, and risk trends across all managed assets.

**Business Value**: Operators gain immediate visibility into their security posture without querying multiple systems.

## Actors

| Actor | Type | Role |
|-------|------|------|
| Operator | Human | Views dashboard, triggers actions |
| Console (Web UI) | System | Renders dashboard components |
| Gateway | Service | Routes and authenticates requests |
| Platform Service | Service | Aggregates data from modules |
| Scanner | Service | Provides scan results and SBOM data |
| Policy Engine | Service | Provides policy verdicts |
| Concelier | Service | Provides advisory data |
| VexLens | Service | Provides VEX consensus data |

## Prerequisites

- User authenticated via Authority (OAuth/OIDC)
- Tenant context established via `X-Tenant-Id` header
- At least one scan completed for data to display

## Flow Diagram

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           Dashboard Data Flow                                    │
└─────────────────────────────────────────────────────────────────────────────────┘

┌────────┐      ┌─────────┐      ┌─────────┐      ┌──────────┐
│Operator│      │ Console │      │ Gateway │      │ Platform │
└───┬────┘      └────┬────┘      └────┬────┘      └────┬─────┘
    │                │                │                │
    │  Open Dashboard│                │                │
    │───────────────>│                │                │
    │                │                │                │
    │                │ GET /api/v1/dashboard          │
    │                │ Authorization: Bearer {jwt}    │
    │                │ X-Tenant-Id: {tenant}          │
    │                │───────────────>│                │
    │                │                │                │
    │                │                │ Validate JWT   │
    │                │                │ Extract claims │
    │                │                │───────┐        │
    │                │                │       │        │
    │                │                │<──────┘        │
    │                │                │                │
    │                │                │ Forward with   │
    │                │                │ X-User-Id      │
    │                │                │───────────────>│
    │                │                │                │
    │                │                │                │  ┌─────────┐
    │                │                │                │  │ Scanner │
    │                │                │                │  └────┬────┘
    │                │                │                │       │
    │                │                │                │ Query scan stats
    │                │                │                │──────>│
    │                │                │                │       │
    │                │                │                │<──────│
    │                │                │                │       │
    │                │                │                │  ┌────────┐
    │                │                │                │  │ Policy │
    │                │                │                │  └───┬────┘
    │                │                │                │      │
    │                │                │                │ Query verdicts
    │                │                │                │─────>│
    │                │                │                │      │
    │                │                │                │<─────│
    │                │                │                │      │
    │                │                │                │  ┌──────────┐
    │                │                │                │  │ Concelier│
    │                │                │                │  └────┬─────┘
    │                │                │                │       │
    │                │                │                │ Query advisories
    │                │                │                │──────>│
    │                │                │                │       │
    │                │                │                │<──────│
    │                │                │                │
    │                │                │ Aggregated     │
    │                │                │ Dashboard DTO  │
    │                │                │<───────────────│
    │                │                │                │
    │                │ 200 OK         │                │
    │                │ {dashboard}    │                │
    │                │<───────────────│                │
    │                │                │                │
    │ Render widgets │                │                │
    │<───────────────│                │                │
    │                │                │                │
```

## Step-by-Step

### 1. User Opens Dashboard
- Operator navigates to Console dashboard
- Browser loads Angular SPA from CDN/static files

### 2. Authentication Check
- Console checks for valid JWT in local storage
- If expired, redirects to Authority login flow
- If valid, proceeds with API calls

### 3. Dashboard API Request
```http
GET /api/v1/dashboard HTTP/1.1
Host: gateway.stellaops.local
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
X-Tenant-Id: acme-corp
Accept: application/json
```

### 4. Gateway Processing
- Validates JWT signature against Authority JWKS
- Extracts tenant from claims or header
- Applies rate limiting and ABAC rules
- Adds internal headers: `X-User-Id`, `X-User-Email`

### 5. Platform Service Aggregation
Platform Service fans out to multiple modules in parallel:

| Query | Module | Endpoint |
|-------|--------|----------|
| Scan statistics | Scanner | `GET /internal/stats?tenant={id}` |
| Policy verdicts | Policy | `GET /internal/verdicts/summary?tenant={id}` |
| Advisory counts | Concelier | `GET /internal/advisories/counts?tenant={id}` |
| VEX coverage | VexLens | `GET /internal/vex/coverage?tenant={id}` |

### 6. Data Aggregation
Platform Service combines responses into dashboard DTO:

```json
{
  "summary": {
    "total_images": 1247,
    "images_scanned_24h": 89,
    "critical_vulns": 12,
    "high_vulns": 145,
    "policy_violations": 3
  },
  "trends": {
    "vuln_trend_7d": [-5, -2, 0, +3, -1, -4, -2],
    "scan_volume_7d": [78, 92, 85, 89, 76, 81, 89]
  },
  "top_vulns": [
    {"cve": "CVE-2024-1234", "severity": "critical", "affected_images": 8}
  ],
  "policy_status": {
    "compliant": 1198,
    "non_compliant": 49,
    "pending": 0
  }
}
```

### 7. Response Delivery
- Platform returns aggregated DTO
- Gateway forwards to Console
- Console renders dashboard widgets

## Data Contracts

### Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | Bearer JWT token |
| `X-Tenant-Id` | Yes | Tenant identifier |
| `Accept` | No | `application/json` (default) |

### Response Schema

```typescript
interface DashboardResponse {
  summary: {
    total_images: number;
    images_scanned_24h: number;
    critical_vulns: number;
    high_vulns: number;
    medium_vulns: number;
    low_vulns: number;
    policy_violations: number;
  };
  trends: {
    vuln_trend_7d: number[];
    scan_volume_7d: number[];
  };
  top_vulns: Array<{
    cve: string;
    severity: 'critical' | 'high' | 'medium' | 'low';
    affected_images: number;
  }>;
  policy_status: {
    compliant: number;
    non_compliant: number;
    pending: number;
  };
  last_updated: string; // ISO-8601
}
```

## Error Handling

| Error | HTTP Status | Recovery |
|-------|-------------|----------|
| Invalid JWT | 401 | Redirect to login |
| Tenant not found | 404 | Show tenant selection |
| Module timeout | 504 | Partial dashboard with stale data indicator |
| Rate limited | 429 | Exponential backoff retry |

## Observability

### Metrics

| Metric | Type | Labels |
|--------|------|--------|
| `dashboard_request_total` | Counter | `tenant`, `status` |
| `dashboard_latency_seconds` | Histogram | `tenant` |
| `dashboard_module_latency_seconds` | Histogram | `module` |

### Trace Context

```
dashboard-request
├── gateway-auth-check
├── platform-aggregate
│   ├── scanner-stats-query
│   ├── policy-verdicts-query
│   ├── concelier-advisories-query
│   └── vexlens-coverage-query
└── response-serialize
```

### Key Log Events

| Event | Level | Fields |
|-------|-------|--------|
| `dashboard.request` | INFO | `tenant_id`, `user_id` |
| `dashboard.module_timeout` | WARN | `module`, `timeout_ms` |
| `dashboard.complete` | INFO | `tenant_id`, `latency_ms` |

## Related Flows

- [Scan Submission Flow](02-scan-submission-flow.md) - How scans that feed the dashboard are created
- [Policy Evaluation Flow](04-policy-evaluation-flow.md) - How policy verdicts are computed
- [Risk Score Dashboard Flow](18-risk-score-dashboard-flow.md) - Detailed risk scoring