# Analytics Dashboard Design

## Overview

The `/admin/analytics` page provides a comprehensive platform analytics dashboard for Investibook administrators. It visualizes workspace usage patterns, user engagement metrics, AI skill invocations, and MCP server performance — giving operators a clear picture of how the platform is being used and where to improve.

## Data Categories

### 1. Platform Overview (KPI Cards)

| Metric | Description |
|--------|-------------|
| Total Workspaces | Count of all workspaces (with trend) |
| Active Users | Unique users in the last 7 days |
| Total Sessions | Chat sessions initiated |
| Avg. Session Duration | Mean time spent per workspace session |

### 2. User Engagement

- **Daily Active Users (DAU)** — Line chart, 30-day trend
- **Visit Frequency Distribution** — Bar chart: 1/day, 2-3/week, weekly, monthly
- **Session Duration Distribution** — Histogram: <5min, 5-15min, 15-30min, 30-60min, 60min+
- **Retention Cohort** — Week-over-week retention rate (simplified bar chart)

### 3. Workspace Analytics

- **Workspace Growth** — Cumulative workspace count over time
- **Workspaces per User Distribution** — Bar chart
- **Source Type Breakdown** — Donut chart: alert, git_repo, mcp_connector, cluster_meta, user_meta
- **Top Workspaces by Activity** — Table: workspace name, message count, last active

### 4. AI Skill Usage

- **Skill Invocation Rate** — Bar chart showing calls per skill
- **Top Skills by Usage** — Ranked list with progress bars
- **Skill Success/Failure Rate** — Stacked bar per skill
- **Skill Usage Trend** — Line chart: daily invocation count over 30 days

### 5. MCP Server Performance

- **Overall Success Rate** — Large gauge / percentage display
- **Call Volume by Server** — Bar chart: clinic, ops-portal, o11y
- **Success Rate by Server** — Horizontal bar with success/failure segments
- **Latency Distribution** — Bar chart: p50, p90, p99 per server
- **MCP Error Breakdown** — Donut chart: timeout, auth_failure, server_error, etc.

### 6. User Behavior Patterns

- **Peak Usage Hours** — Heatmap (hour × day-of-week)
- **Feature Adoption** — Radar/bar chart: chat, sources, studio, screenshots, file-browse
- **User Segments** — Pie: power users (daily), regular (weekly), casual (monthly)
- **Message Volume Trend** — Area chart: messages per day

## Page Layout

```
┌──────────────────────────────────────────────────────────┐
│  ← Back to workspaces          Analytics Dashboard       │
├──────────────────────────────────────────────────────────┤
│  [Workspaces: 128] [Active Users: 47] [Sessions: 1.2k]  │
│  [Avg Duration: 18m]                                     │
├────────────────────────────┬─────────────────────────────┤
│  Daily Active Users (line) │  Workspace Growth (line)    │
├────────────────────────────┼─────────────────────────────┤
│  Skill Invocations (bar)   │  MCP Success Rate (bars)    │
├────────────────────────────┼─────────────────────────────┤
│  Peak Usage Hours (heatmap)│  Source Types (donut)        │
├────────────────────────────┼─────────────────────────────┤
│  Feature Adoption (bar)    │  User Segments (pie)         │
├────────────────────────────┼─────────────────────────────┤
│  MCP Latency (bar)         │  Retention Cohort (bar)      │
├────────────────────────────┴─────────────────────────────┤
│  Top Workspaces by Activity (table)                      │
└──────────────────────────────────────────────────────────┘
```

## Technical Approach

- **Client component** (`'use client'`) — consistent with all Investibook pages
- **Inline styles** — project convention; no CSS modules or Tailwind utility classes in components
- **UI library**: `@tidbcloud/uikit` for layout primitives (`Stack`, `Group`, `Box`, `Card`, `Text`, `Title`, `Badge`)
- **Charts**: Pure SVG/CSS charts for lightweight rendering (no additional chart library dependency for admin-only page)
- **Mock data**: All data is generated in a co-located `mockData.ts` module using deterministic seed patterns for consistent rendering
- **Auth guard**: Admin-only — reuses the `ADMIN_EMAILS` gate pattern from existing `/admin/*` pages
- **API-ready**: Mock data structure mirrors planned backend API response shapes, enabling easy swap to real endpoints later

## File Structure

```
app/admin/analytics/
  page.tsx          — Main dashboard page component
  mockData.ts       — Mock data generators
  charts.tsx        — Reusable SVG chart components
```

## Mock Data → API Migration Path

When analytics backend is ready, replace mock imports in `page.tsx` with `fetchWithAuth()` calls:

```ts
// Before (mock)
import { getOverviewKPIs, getDailyActiveUsers } from './mockData';

// After (API)
const kpis = await fetchWithAuth('/api/admin/analytics/overview').then(r => r.json());
const dau = await fetchWithAuth('/api/admin/analytics/dau').then(r => r.json());
```