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

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

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)