Dashboard Analytics

Status

Future canonical contract.

This document defines the target aggregate contract for replacing the Dashboard customer-signals concept preview with real analytics.

Purpose

Provide a workspace-scoped aggregate that powers the Account Dashboard’s future analytics layer without forcing the client to reconstruct signal, triage, and outcome metrics from raw event streams.

The contract is designed to support:

dashboard summary cards
top friction theme modules
recent operational activity
recommendation generation
progressive rollout from readiness-only surfaces to signal and outcome metrics

Scope rules

The aggregate must be scoped to a single workspace unless an explicit org-wide contract is later approved.
The response must never leak data across workspace or org boundaries.
The aggregate may mix live operational counts with derived analytics, but every field must be clearly defined by source and interpretation.
Fields that are not yet available may be omitted or returned as null, but the contract must distinguish unavailable data from zero values.

Endpoint

GET /workspaces/{workspaceId}/dashboard

Query parameters (future, optional):

range — dashboard time range such as 24h, 7d, 30d
include — optional payload groups to include when partial loading is needed
asOf — optional snapshot timestamp for reproducible views

Response shape

{
  "workspaceId": "ws_123",
  "generatedAt": "2026-03-23T12:00:00.000Z",
  "range": "7d",
  "readinessSummary": {},
  "customerSignalSummary": {},
  "systemSummary": {},
  "outcomeSummary": {},
  "topFrictionThemes": [],
  "recentActivity": [],
  "recommendedActions": [],
  "availability": {}
}

Payload groups

`readinessSummary`

Operational setup and coverage state.

Expected fields:

workspaceReadiness
channels
knowledgeBases
agents

This group remains the source for the current readiness layer already present on the dashboard.

`customerSignalSummary`

What users are expressing across comments, reviews, and conversations.

Minimum future fields:

dissatisfactionDetected
severeNegativeDetected
successSignalsDetected
topSignalThemes

Optional later fields:

inboundVolume
negativeSignalRate
unresolvedFollowUpCount

`systemSummary`

How the platform classified, routed, and responded.

Minimum future fields:

escalationsTriggered
kbGapsDetected
autoHandledCount
humanAssistedCount
triageCompletedCount

Optional later fields:

avgResponseTimeMs
replyGeneratedCount
replySentCount
confidenceDistribution

`outcomeSummary`

What happened after the workflow ran.

These fields must remain optional until outcome attribution is formally approved.

Fields:

resolvedCount
recoveredCount
reopenedCount
successfulHandoffCount
sentimentImprovementRate

`topFrictionThemes`

Ranked cluster output for recurring negative or high-friction topics.

[
  {
    "id": "refund_expectations",
    "label": "Refund expectations",
    "count": 8,
    "severity": "high",
    "kbGapCount": 3,
    "sampleChannels": ["reviews", "web-chat"]
  }
]

Required fields:

id
label
count
severity

Optional fields:

kbGapCount
sampleChannels
trendDirection

`recentActivity`

Lightweight dashboard-ready operational events.

This is not the raw event stream. It is a curated recent-activity feed suitable for the dashboard.

[
  {
    "id": "evt_123",
    "type": "escalation_triggered",
    "title": "Escalation triggered",
    "description": "High-risk complaint routed to human review.",
    "timestamp": "2026-03-23T11:52:00.000Z"
  }
]

`recommendedActions`

Curated next actions derived from readiness, signal, system, and outcome data.

[
  {
    "id": "kb_gap_refunds",
    "title": "Close the refund policy knowledge gap",
    "description": "Refund-related complaints are rising and grounding quality is weak.",
    "priority": "high",
    "targetHref": "/account/knowledge-bases"
  }
]

`availability`

Per-group data readiness.

{
  "readinessSummary": "available",
  "customerSignalSummary": "available",
  "systemSummary": "available",
  "outcomeSummary": "unavailable"
}

Allowed values:

available
partial
unavailable
demo

This lets the UI distinguish:

true zero values
unavailable data
temporary concept/demo values

Field availability rules

readinessSummary should be available first.
customerSignalSummary and systemSummary are the first analytics groups to graduate from concept preview to live data.
outcomeSummary must not be treated as trustworthy until attribution and recovery logic are explicitly defined in canonical docs.

Security and privacy constraints

No message content may be returned in this aggregate.
No PII may appear in dashboard analytics payloads.
Payloads must use internal identifiers and safe summary fields only.
Any sampled text or examples require a separate approved contract.

Dashboard Analytics

Status

Purpose

Scope rules

Endpoint

Response shape

Payload groups

readinessSummary

customerSignalSummary

systemSummary

outcomeSummary

topFrictionThemes

recentActivity

recommendedActions

availability