Dashboard

# Dashboard

The dashboard provides an at-a-glance view of your workspace with key performance indicators, interactive charts, top records, and recent activity. It renders at `/dashboard` and serves as the default landing page after login.

## Overview

The dashboard is built on the platform's block system and view infrastructure. What users see as "the dashboard" is actually a set of resolved blocks rendered via `BlockGrid`. The dashboard can be customized through the view system, and older `config.dashboard.sections` still render through the same resolver stack as a read-only fallback until a persisted view is created.

## Key Concepts

### KPI Widgets

KPI cards display key metrics as large numbers with optional trend indicators. They are rendered as `stat-cards` block type, which accepts an array of stat objects (label, value, optional change percentage, optional icon). The dashboard server resolver computes these values from entity counts, activity summaries, and custom queries.

### Chart Types

The platform provides two reusable chart components in `features/charts/`:

**RadarChart** -- Single-series or multi-series radar charts built on Recharts. The `RadarChart` component takes data points with `name`, `value`, and optional `fullMark`. The `MultiSeriesRadarChart` supports overlaying multiple data series on the same polar grid. Requires at least 3 data points to render. Used in entity scoring displays and tool output sections.

**BubbleChart** -- Scatter-based bubble chart where each point has `x`, `y`, and `z` (size) dimensions. Built on Recharts `ScatterChart` with `ZAxis` for bubble sizing. Includes a custom tooltip that displays all non-coordinate fields. Used on the Insights page for the opportunity map.

Both chart components use CSS variables for colors (`var(--primary)`, `var(--border)`) and shared constants from `lib/chart-colors.ts` (`CHART_COLORS`, `CHART_TOOLTIP_STYLE`, `CHART_AXIS_TICK`).

### Dashboard Block Resolution

Dashboard blocks are resolved server-side before rendering. `resolveView()` is the canonical entry point, and it delegates dashboard-style collection/aggregation blocks to the internal `resolveServerBlocks()` helper in `features/blocks/server/resolve-server-blocks.ts`:

- `stat-cards` -- queries entity counts, activity metrics, or custom KPI sources
- `chart` -- fetches time-series or categorical data for bar/line/pie charts
- `table` -- queries entity lists with specified columns
- `activity` -- fetches recent activity records
- `entity-feed` -- fetches ranked/filtered entity lists

The resolved blocks (with data attached) are passed to `BlockGrid` for client-side rendering.

### Dashboard Compatibility

Legacy dashboards used an `EntityTypeConfig.dashboard.sections` format with section arrays. The `migrateDashboardSections()` function converts these to canonical block configs, and the list page now wraps them in a deterministic synthetic view only when no persisted list views exist.

That keeps older dashboard configs visible without mutating the database during page render. Once a user creates a persisted list view, that stored view becomes the canonical editable surface.

### Customization via View System

The dashboard can be customized through views:

1. Navigate to an entity type page
2. Use the ViewTabs UI to create or edit views
3. Add blocks via the ViewEditor (stat-cards, charts, tables, etc.)
4. Blocks are resolved server-side and rendered via BlockGrid

Workspace views (page_type: 'workspace') support regions (header, leftRail, main, rightRail, drawer) and tabs for more complex dashboard layouts. The `manageView` agent tool can also create and modify dashboard views programmatically.

## What You'll See

- **KPI cards** -- Key metrics across your data (total records, active items, etc.)
- **Charts** -- Records by type, activity trends, and custom visualizations
- **Top records** -- Highest-priority items across all data types
- **Recent activity** -- Latest changes made by users and agents

## For Agents

- **Relevant tools:** `getEntityStats` (aggregate counts), `searchEntities` (top records), `manageView` (create/modify dashboard views)
- **Permissions required:** `entities.own.read` minimum; `views.team.write` for dashboard customization
- **Common workflows:** Agents can query `getEntityStats` to understand workspace state, then use `manageView` to create custom dashboard views with targeted KPIs and charts

## Manual Test Script

### Prerequisites

- Logged in as any role (viewer or above)
- At least one data type configured with some records

### Happy Path

1. **Navigate to dashboard**
   - Go to `/dashboard`
   - Expected: Page loads within 3 seconds, main content area visible
   - Expected: Navigation sidebar visible on left

2. **Verify KPI cards**
   - Expected: At least one KPI card visible with a numeric value
   - Expected: No "NaN" or "undefined" values displayed

3. **Verify charts**
   - Expected: At least one chart renders (bar, pie, or line)
   - Expected: Chart has readable labels and legends
   - Click **Records by Type** -- expected: navigates to the clicked record type's filtered list page
   - Click **Score Distribution** -- expected: navigates to the clicked record detail page

4. **Verify activity feed**
   - Expected: Recent activity section shows timestamped entries
   - Expected: Each entry has an actor name and action description

5. **Check mobile viewport (375x667)**
   - Expected: Dashboard reorganizes to single column
   - Expected: All sections still accessible via scroll
   - Expected: No horizontal overflow
   - At 390px, expected: the main content grid's rendered width and scroll
     width stay within its parent; chart cards retain both borders and complete
     bars even when a tenant has hundreds of data types

### Edge Cases

- **Empty workspace:** Dashboard should show empty states with guidance, not blank sections
- **Viewer role:** All data should be read-only, no edit controls visible
- **Network error:** Graceful degradation with error messages, not a blank crash

### Regression Checks

- [ ] Sidebar navigation works from dashboard
- [ ] No console errors on page load
- [ ] Agent sidebar can be opened from dashboard
- [ ] `e2e/mobile-overflow.spec.ts` measures the dashboard main grid itself at
      390px (a body-level overflow check alone cannot detect ancestor-clipped
      min-content tracks)

## Related Modules

- **Block System** (`features/blocks/`) -- dashboard content renders as blocks
- **Views** (`features/views/`) -- dashboard configuration stored as views
- **Charts** (`features/charts/`) -- RadarChart and BubbleChart components
- **Entity System** (`features/entities/`) -- data source for KPIs and charts
- **Insights** -- product-specific analytics dashboard (separate from the general dashboard)