Account – Dashboard

Route

Path: /account or /account/dashboard (TBD)
Parent: README.md

Purpose (business goal)

Provide an at-a-glance operational control surface for the current workspace context.

The Dashboard should help an operator answer three questions quickly:

Is the workspace healthy and ready?
What needs attention right now?
What should I do next?

This is not primarily a BI/reporting page. It is an operational summary surface that prioritizes readiness, blockers, coverage, and next actions across:

channels
knowledge bases
agents
app readiness
recent operational activity

The page may also contain a clearly labeled concept-preview layer for future customer-signal and outcome metrics, but that layer must remain visibly secondary until backed by real analytics data.

User roles & permissions

Workspace Admin, Manager, Analyst (read-only)
Permissions: workspace.view, channels.view, kb.view (TBD)

Reference: Roles & Permissions Model

Layout structure

Application shell (persistent)
- Left navigation rail with grouped sections (two states: default and narrowed):
  - Get started (includes a 3-segment onboarding progress indicator; see App Shell (Navigation, Search, Assistant Sidebar))
  - Account (Dashboard, Channels, Knowledge bases, Workspaces, Settings)
  - Comment Responder (Comments, Reviews)
  - Chatti Live (Conversations, Agents)
- Bottom-left user menu trigger (profile-only)
Top bar (page header)
- Breadcrumb: Account > Dashboard
  - The Account icon in the breadcrumb toggles the left navigation rail between default and narrowed states.
- Global platform search input
- Chatti Live toggle
  - When Chatti Live sidebar is hidden: a Chatti Live button appears next to the search field
  - When Chatti Live sidebar is shown: the button disappears (sidebar provides its own header/controls)
Primary canvas
- Standard account top section with px-6 py-5 and a single outer border-b
- Header block
  - Page title: Dashboard
- Toolbar row
  - Shared account toolbar layout below the title, matching Workspaces and Knowledge bases
  - Includes the shared workspace-filter combobox with leading workspace icon
    - Default behavior should resolve to the current/default workspace when possible, not an all-workspaces rollup
    - All workspaces remains available as an explicit override for rare cross-workspace review
- Main content region
  - Uses p-6
  - Organized in this order:
    1. Health strip (4 summary cards)
    2. Needs attention (priority actions / blockers)
    3. Customer signals & outcomes (concept preview; clearly labeled when using demo data)
    4. Operational grid (two-column layout)
- Health strip
  - Four cards in a responsive row:
    - Workspace readiness
    - Channels
    - Knowledge bases
    - Agents
  - Each card shows:
    - primary metric
    - supporting status line
    - optional severity indicator
    - one contextual CTA
- Needs attention
  - Full-width panel directly below the health strip
  - Ranked list of operational blockers and recommended next actions
  - Highest-priority module on the page after the health strip
- Customer signals & outcomes
  - Full-width concept-preview section used to evaluate future dashboard evolution
  - Must be visibly labeled as Concept preview or Demo data until backed by real analytics
  - May include:
    - compact customer-signal cards such as dissatisfaction detected, recovered/resolved, escalations, or KB gaps
    - ranked friction themes
    - success signals or opportunity areas
  - Must remain subordinate to the readiness and blocker surfaces
- Operational grid
  - Two-column layout on desktop, single-column stack on smaller widths
  - Left column (operational status)
    - Channels status
    - Knowledge base readiness
    - Agent coverage
  - Right column (context + action)
    - Recent activity
    - Quick actions
    - Recommended next steps
Right sidebar (Chatti Live assistant)
- Docked sidebar with header controls (overflow + close)
- Assistant content area (welcome + guidance)
- Quick actions: Add documents, Add new knowledge base, Link another knowledge base (TBD behavior)
- Input dock: “Ask your question”
Profile-only user menu (bottom-left)
- Shows user identity summary (name/email)
- Menu items: Profile, Billing, Activity log, Log out

Components used

Workspace Card: Component: Workspace Card (workspace context)
Knowledge Base Card: Component: Knowledge Base Card (status preview)
Dashboard health card (component doc TBD)
Priority action list / feed (component doc TBD)
Customer signals concept preview (component doc TBD)
Recent activity feed (component doc TBD)
Quick action group (component doc TBD)
Shell/navigation (component docs TBD):
- Left navigation rail + section groups
- Breadcrumb header
- Global search input
- Profile-only user menu (trigger + dropdown)
- Chatti Live sidebar + toggle button

States

Empty
- New or minimally configured workspace
- Health strip still renders, but values show 0 / Not started
- Needs attention should guide setup instead of showing generic emptiness
Loading
- Health strip shows skeleton cards
- Needs attention and grid modules show skeleton blocks
Error
- Non-destructive module errors should fail independently where possible
- Full-page error only when the dashboard cannot resolve any core aggregate data
Complete
- Health strip, attention panel, concept preview, and operational modules render

Concept preview substates:

Demo data visible
- Used to evaluate future product direction before real analytics are available
Future metrics unavailable
- Shows explanatory empty states rather than misleading production-like numbers

UI substates (non-blocking):

Left nav: default / narrowed
Chatti Live sidebar: hidden / shown
Profile menu: closed / open
Global search: idle / querying / no results (TBD)

Business logic (high-level)

Compute readiness across workspace layers:
- workspace activation/readiness
- channel health and connectivity
- knowledge base completeness
- agent coverage and activation
- app readiness where applicable
Prioritize actionability over vanity metrics.
- The page should surface blockers first, not generic charts.
Distinguish between:
- Readiness metrics: current setup, coverage, activation, and configuration health
- Customer-signal metrics: what users are expressing across comments, reviews, and conversations
- Outcome metrics: whether the platform helped improve or resolve the situation
Dashboard modules should be derived from canonical domain entities already documented in:
Suggested status derivations:
- Workspace readiness
  - Not started
  - In progress
  - Operational
  - Needs attention
- Channels
  - connected vs disconnected totals
  - channel-family distribution
- Knowledge bases
  - complete vs incomplete totals
  - default KB visibility
- Agents
  - active vs inactive totals
  - channel coverage / unassigned or inactive coverage gaps
Concept-preview metrics may illustrate future value areas such as:
- dissatisfaction detected
- recovered or resolved interactions
- escalations to human review
- KB gaps affecting reply quality
- top friction themes
Approved future analytics requirements for this route:
- a minimum taxonomy of signal, system, and outcome metrics
- dashboard aggregates for customer signal summary, system/triage summary, outcome summary, and friction themes
- enabling event instrumentation for customer signals, triage, KB gaps, and outcomes
Guardrail:
- until production analytics exist, concept-preview metrics must never be presented as authoritative live truth
Global platform search must be permission-scoped (org/workspace + RBAC) and must not leak data across boundaries.
Chatti Live assistant sidebar:
- Shown/hidden via the top-bar toggle behavior described above.
- Implementation note: assistant is backed by Gemini in a Chrome browser context (details TBD; must comply with platform security constraints).

Domain refs:

API dependencies

GET /workspaces/{id}/dashboard (recommended aggregate endpoint; future)
- Suggested payload groups:
  - readiness summary
  - customer signal summary
  - outcome summary
  - channels summary
  - KB summary
  - agent summary
  - recent activity
  - recommended actions
Global search APIs (TBD)
Chatti Live assistant integration points (TBD)

MVP note:

Until a dedicated aggregate endpoint exists, the dashboard may compose its modules from existing workspace, channels, KB, and agent data sources.
Concept-preview metrics may use clearly labeled demo data to evaluate product direction, but that layer must be visually separated from the real operational data.

Enterprise constraints

Must not leak cross-workspace data in aggregates
Global search and assistant responses must never cross org/workspace boundaries.
Assistant must not emit/store PII or secrets in logs/analytics; follow Security & Compliance.

Edge cases

Workspace has channel connections but no outbound permissions
Workspace has connected channels but no active agent coverage
Workspace has complete KBs but no linked channels
Workspace has channels assigned to inactive agents
Recommended actions list is empty despite incomplete setup
- fall back to showing the highest-value quick actions
Customer-signal concept preview exists but no analytics pipeline is connected yet
- show explicit Concept preview / Demo data labeling
Chatti Live assistant not available (plan/permission/feature flag) → sidebar remains hidden; no toggle shown (TBD)
Global search returns results the user cannot access → results must be filtered out (strict)
User dismisses Get Started overlay before completing onboarding; Dashboard becomes the visible surface but activation remains incomplete (TBD)

Security & compliance considerations

Enforce scope checks on all aggregates

Reference: Security & Compliance

Analytics events (if applicable)

account.dashboard.viewed
account.dashboard.health_card_clicked
account.dashboard.priority_action_clicked
account.dashboard.concept_preview_viewed
account.dashboard.concept_metric_clicked
account.dashboard.quick_action_clicked
account.dashboard.recommendation_clicked
Search and assistant interactions: TBD (must not include message content / PII)

Reference: Analytics Events (MVP)

Future evolution rule

The Dashboard is expected to evolve as the platform matures.

It should be treated as a flexible operational surface, not a frozen layout.

Safe future changes include:

adding time-based trends or charts
introducing workspace switching or scope controls
refining readiness scoring
expanding predictive recommendations
increasing assistant integration

Constraint:

future additions must preserve the page’s primary job as an actionable operational summary, not turn it into a generic analytics page.

Rollout phases

Phase 1 — Current state

real readiness and blocker surfaces
clearly labeled concept-preview metrics with demo data

Phase 2 — First real analytics rollout

replace concept-preview signal and system metrics with real data where available
minimum target metrics:
- dissatisfaction detected
- severe negative count
- escalations triggered
- KB gaps affecting replies
- top friction themes

Phase 3 — Outcome rollout

add outcome metrics only after attribution and governance rules are mature enough to support trustworthy recovery and resolution claims