VoiceAssist Admin Panel - Feature Specifications

Document Version: 1.0.0 Last Updated: 2025-11-21 Status: Final Specification Target Release: v1.0.0

Table of Contents

1. Overview
2. Dashboard Features
3. Knowledge Base Management
4. AI Model Configuration
5. Analytics
6. Integration Management
7. Technical Implementation
8. Testing Strategy

1. Overview

1.1 Technology Stack

The VoiceAssist Admin Panel is built with modern web technologies optimized for administrative interfaces and data visualization:

Core Framework:

• React 18.2+ with TypeScript 5.0+
• Vite 5.0+ (build tool and dev server)
• React Router v6 (client-side routing)

UI Framework:

• Tailwind CSS 3.4+ (utility-first styling)
• Tremor 3.x (dashboard and chart components)
• Headless UI (accessible component primitives)
• Heroicons (icon library)

Data Management:

• TanStack Table v8 (advanced table functionality)
• TanStack Query v5 (server state management)
• Zustand (client state management)

Visualization:

• Recharts 2.x (charts via Tremor)
• D3.js 7.x (custom visualizations)

Real-time Communication:

• Socket.io Client 4.x (WebSocket connections)
• Server-Sent Events (SSE) for updates

Form Management:

• React Hook Form 7.x
• Zod (schema validation)

Development Tools:

• ESLint + Prettier
• Vitest (unit testing)
• Playwright (e2e testing)
• MSW (API mocking)

1.2 Design Principles

1. Information Density

• Maximize useful information per screen
• Use progressive disclosure for complex data
• Implement responsive tables and charts

2. Real-time Updates

• Live metrics without page refresh
• WebSocket connections for critical data
• Optimistic UI updates

3. Performance

• Virtualized tables for large datasets
• Lazy loading of heavy components
• Code splitting by route

4. Accessibility

• WCAG 2.1 AA compliance
• Keyboard navigation throughout
• Screen reader optimized

5. Error Handling

• Graceful degradation
• Clear error messages
• Retry mechanisms

1.3 Architecture

/admin-panel
├── /src
│   ├── /components
│   │   ├── /dashboard     # Dashboard widgets
│   │   ├── /kb            # KB management components
│   │   ├── /ai-config     # AI configuration components
│   │   ├── /analytics     # Analytics components
│   │   ├── /integrations  # Integration components
│   │   └── /common        # Shared components
│   ├── /hooks             # Custom React hooks
│   ├── /services          # API services
│   ├── /stores            # Zustand stores
│   ├── /types             # TypeScript types
│   ├── /utils             # Utility functions
│   └── /pages             # Route pages
├── /tests
│   ├── /unit
│   ├── /integration
│   └── /e2e
└── /public

2. Dashboard Features

2.1 Real-time Metrics Display

Priority: P0 (Critical) Effort: 5 days Dependencies: WebSocket connection, /api/admin/metrics endpoint

Specification

Display key system metrics updated in real-time via WebSocket:

• Active sessions count
• Requests per minute
• Average response time
• Error rate
• Cost per hour

Visual Design:

• 5 metric cards in a grid layout
• Large numbers with trend indicators
• Sparkline charts showing 1-hour history
• Color-coded status (green/yellow/red)

Component Implementation

// src/components/dashboard/RealTimeMetrics.tsx
import { useEffect, useState } from 'react';
import { Card, Metric, Text, Flex, BadgeDelta, AreaChart } from '@tremor/react';
import { useWebSocket } from '@/hooks/useWebSocket';
import type { SystemMetrics } from '@/types/metrics';

interface MetricCardProps {
  title: string;
  value: number;
  unit?: string;
  trend?: number;
  trendType?: 'increase' | 'decrease' | 'unchanged';
  history?: number[];
  format?: (value: number) => string;
}

const MetricCard: React.FC<MetricCardProps> = ({
  title,
  value,
  unit = '',
  trend,
  trendType = 'unchanged',
  history = [],
  format = (v) => v.toString(),
}) => {
  const chartData = history.map((val, idx) => ({
    time: idx,
    value: val,
  }));

  return (
    <Card decoration="top" decorationColor={
      trendType === 'increase' ? 'green' :
      trendType === 'decrease' ? 'red' :
      'gray'
    }>
      <Flex>
        <Text>{title}</Text>
        {trend !== undefined && (
          <BadgeDelta deltaType={trendType}>
            {trend > 0 ? '+' : ''}{trend}%
          </BadgeDelta>
        )}
      </Flex>
      <Metric>{format(value)}{unit}</Metric>
      {history.length > 0 && (
        <AreaChart
          className="mt-4 h-12"
          data={chartData}
          index="time"
          categories={['value']}
          colors={[trendType === 'increase' ? 'green' : trendType === 'decrease' ? 'red' : 'gray']}
          showXAxis={false}
          showYAxis={false}
          showLegend={false}
          showGridLines={false}
          showTooltip={false}
          curveType="natural"
        />
      )}
    </Card>
  );
};

export const RealTimeMetrics: React.FC = () => {
  const [metrics, setMetrics] = useState<SystemMetrics | null>(null);
  const [history, setHistory] = useState<Map<string, number[]>>(new Map());

  const { data, isConnected } = useWebSocket<SystemMetrics>('metrics', {
    reconnect: true,
    reconnectInterval: 5000,
  });

  useEffect(() => {
    if (data) {
      setMetrics(data);

      // Update history for sparklines
      setHistory((prev) => {
        const newHistory = new Map(prev);

        const updateHistory = (key: string, value: number) => {
          const current = newHistory.get(key) || [];
          const updated = [...current, value].slice(-60); // Keep last 60 points
          newHistory.set(key, updated);
        };

        updateHistory('activeSessions', data.activeSessions);
        updateHistory('requestsPerMinute', data.requestsPerMinute);
        updateHistory('avgResponseTime', data.avgResponseTime);
        updateHistory('errorRate', data.errorRate);
        updateHistory('costPerHour', data.costPerHour);

        return newHistory;
      });
    }
  }, [data]);

  if (!metrics) {
    return (
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4">
        {[...Array(5)].map((_, i) => (
          <Card key={i} className="animate-pulse">
            <div className="h-20 bg-gray-200 rounded"></div>
          </Card>
        ))}
      </div>
    );
  }

  return (
    <div className="space-y-4">
      {!isConnected && (
        <div className="bg-yellow-50 border-l-4 border-yellow-400 p-4">
          <p className="text-sm text-yellow-700">
            Real-time updates disconnected. Attempting to reconnect...
          </p>
        </div>
      )}

      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4">
        <MetricCard
          title="Active Sessions"
          value={metrics.activeSessions}
          trend={metrics.sessionsTrend}
          trendType={metrics.sessionsTrend > 0 ? 'increase' : 'decrease'}
          history={history.get('activeSessions')}
        />

        <MetricCard
          title="Requests/min"
          value={metrics.requestsPerMinute}
          trend={metrics.requestsTrend}
          trendType={metrics.requestsTrend > 0 ? 'increase' : 'decrease'}
          history={history.get('requestsPerMinute')}
          format={(v) => v.toFixed(1)}
        />

        <MetricCard
          title="Avg Response Time"
          value={metrics.avgResponseTime}
          unit="ms"
          trend={metrics.responseTrend}
          trendType={metrics.responseTrend < 0 ? 'increase' : 'decrease'}
          history={history.get('avgResponseTime')}
          format={(v) => Math.round(v).toString()}
        />

        <MetricCard
          title="Error Rate"
          value={metrics.errorRate}
          unit="%"
          trend={metrics.errorTrend}
          trendType={metrics.errorTrend > 0 ? 'decrease' : 'increase'}
          history={history.get('errorRate')}
          format={(v) => v.toFixed(2)}
        />

        <MetricCard
          title="Cost/Hour"
          value={metrics.costPerHour}
          unit=""
          trend={metrics.costTrend}
          trendType={metrics.costTrend > 0 ? 'decrease' : 'increase'}
          history={history.get('costPerHour')}
          format={(v) => `$${v.toFixed(2)}`}
        />
      </div>
    </div>
  );
};

Custom Hook for WebSocket

// src/hooks/useWebSocket.ts
import { useEffect, useState, useRef } from "react";
import io, { Socket } from "socket.io-client";

interface UseWebSocketOptions {
  reconnect?: boolean;
  reconnectInterval?: number;
}

interface UseWebSocketReturn<T> {
  data: T | null;
  isConnected: boolean;
  error: Error | null;
  emit: (event: string, data: any) => void;
}

export function useWebSocket<T = any>(event: string, options: UseWebSocketOptions = {}): UseWebSocketReturn<T> {
  const { reconnect = true, reconnectInterval = 5000 } = options;

  const [data, setData] = useState<T | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const socketRef = useRef<Socket | null>(null);

  useEffect(() => {
    const socket = io(import.meta.env.VITE_WEBSOCKET_URL || "http://localhost:5056", {
      reconnection: reconnect,
      reconnectionDelay: reconnectInterval,
      transports: ["websocket"],
    });

    socketRef.current = socket;

    socket.on("connect", () => {
      setIsConnected(true);
      setError(null);
    });

    socket.on("disconnect", () => {
      setIsConnected(false);
    });

    socket.on("error", (err: Error) => {
      setError(err);
    });

    socket.on(event, (newData: T) => {
      setData(newData);
    });

    return () => {
      socket.disconnect();
    };
  }, [event, reconnect, reconnectInterval]);

  const emit = (eventName: string, eventData: any) => {
    if (socketRef.current?.connected) {
      socketRef.current.emit(eventName, eventData);
    }
  };

  return { data, isConnected, error, emit };
}

Type Definitions

// src/types/metrics.ts
export interface SystemMetrics {
  activeSessions: number;
  sessionsTrend: number;
  requestsPerMinute: number;
  requestsTrend: number;
  avgResponseTime: number;
  responseTrend: number;
  errorRate: number;
  errorTrend: number;
  costPerHour: number;
  costTrend: number;
  timestamp: string;
}

Unit Tests

// tests/unit/components/dashboard/RealTimeMetrics.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';
import { RealTimeMetrics } from '@/components/dashboard/RealTimeMetrics';
import * as useWebSocketModule from '@/hooks/useWebSocket';

vi.mock('@/hooks/useWebSocket');

describe('RealTimeMetrics', () => {
  it('should render loading state initially', () => {
    vi.mocked(useWebSocketModule.useWebSocket).mockReturnValue({
      data: null,
      isConnected: false,
      error: null,
      emit: vi.fn(),
    });

    render(<RealTimeMetrics />);

    const cards = screen.getAllByRole('article');
    expect(cards).toHaveLength(5);
    expect(cards[0]).toHaveClass('animate-pulse');
  });

  it('should render metrics when data is available', async () => {
    const mockMetrics = {
      activeSessions: 42,
      sessionsTrend: 5.2,
      requestsPerMinute: 123.5,
      requestsTrend: -2.1,
      avgResponseTime: 145,
      responseTrend: 3.4,
      errorRate: 0.05,
      errorTrend: -0.02,
      costPerHour: 2.45,
      costTrend: 1.2,
      timestamp: '2025-11-21T10:00:00Z',
    };

    vi.mocked(useWebSocketModule.useWebSocket).mockReturnValue({
      data: mockMetrics,
      isConnected: true,
      error: null,
      emit: vi.fn(),
    });

    render(<RealTimeMetrics />);

    await waitFor(() => {
      expect(screen.getByText('42')).toBeInTheDocument();
      expect(screen.getByText('123.5')).toBeInTheDocument();
      expect(screen.getByText('145ms')).toBeInTheDocument();
      expect(screen.getByText('0.05%')).toBeInTheDocument();
      expect(screen.getByText('$2.45')).toBeInTheDocument();
    });
  });

  it('should show disconnection warning', () => {
    vi.mocked(useWebSocketModule.useWebSocket).mockReturnValue({
      data: null,
      isConnected: false,
      error: null,
      emit: vi.fn(),
    });

    render(<RealTimeMetrics />);

    expect(screen.getByText(/Real-time updates disconnected/i)).toBeInTheDocument();
  });
});

Accessibility Notes

• All metric cards have proper ARIA labels
• Trend indicators use semantic colors and text
• Loading states announced to screen readers
• Keyboard navigation between cards
• Focus indicators on interactive elements

2.2 System Health Indicators

Priority: P0 (Critical) Effort: 3 days Dependencies: /api/admin/health endpoint

Specification

Visual indicators for critical system components:

• API server status
• Database connection
• Redis cache
• Vector database
• External integrations (Nextcloud, email)

Visual Design:

• Status badges with icons (check/warning/error)
• Last check timestamp
• Response time for each component
• Click to view detailed logs

Component Implementation

// src/components/dashboard/SystemHealthIndicators.tsx
import { useState } from 'react';
import { Card, Badge, Table, TableHead, TableRow, TableHeaderCell, TableBody, TableCell, Button } from '@tremor/react';
import { CheckCircleIcon, ExclamationCircleIcon, XCircleIcon, ArrowPathIcon } from '@heroicons/react/24/outline';
import { useQuery } from '@tanstack/react-query';
import { adminApi } from '@/services/api';
import type { HealthStatus } from '@/types/health';

interface HealthIndicatorProps {
  status: 'healthy' | 'degraded' | 'down';
  size?: 'sm' | 'md' | 'lg';
}

const HealthIndicator: React.FC<HealthIndicatorProps> = ({ status, size = 'md' }) => {
  const config = {
    healthy: { icon: CheckCircleIcon, color: 'green', label: 'Healthy' },
    degraded: { icon: ExclamationCircleIcon, color: 'yellow', label: 'Degraded' },
    down: { icon: XCircleIcon, color: 'red', label: 'Down' },
  };

  const { icon: Icon, color, label } = config[status];
  const iconSize = size === 'sm' ? 'h-4 w-4' : size === 'md' ? 'h-5 w-5' : 'h-6 w-6';

  return (
    <Badge color={color} icon={Icon} size={size}>
      {label}
    </Badge>
  );
};

export const SystemHealthIndicators: React.FC = () => {
  const [showDetails, setShowDetails] = useState<string | null>(null);

  const { data: health, isLoading, refetch, isRefetching } = useQuery({
    queryKey: ['system-health'],
    queryFn: () => adminApi.getSystemHealth(),
    refetchInterval: 30000, // Refresh every 30 seconds
  });

  if (isLoading) {
    return (
      <Card>
        <div className="animate-pulse space-y-4">
          <div className="h-4 bg-gray-200 rounded w-1/4"></div>
          <div className="space-y-2">
            {[...Array(5)].map((_, i) => (
              <div key={i} className="h-12 bg-gray-200 rounded"></div>
            ))}
          </div>
        </div>
      </Card>
    );
  }

  if (!health) {
    return (
      <Card>
        <p className="text-gray-500">Unable to load health status</p>
      </Card>
    );
  }

  const overallStatus = health.components.every(c => c.status === 'healthy')
    ? 'healthy'
    : health.components.some(c => c.status === 'down')
    ? 'down'
    : 'degraded';

  return (
    <Card>
      <div className="flex items-center justify-between mb-4">
        <div className="flex items-center gap-3">
          <h3 className="text-lg font-semibold text-gray-900">System Health</h3>
          <HealthIndicator status={overallStatus} size="lg" />
        </div>
        <Button
          variant="secondary"
          size="xs"
          icon={ArrowPathIcon}
          onClick={() => refetch()}
          loading={isRefetching}
        >
          Refresh
        </Button>
      </div>

      <Table>
        <TableHead>
          <TableRow>
            <TableHeaderCell>Component</TableHeaderCell>
            <TableHeaderCell>Status</TableHeaderCell>
            <TableHeaderCell>Response Time</TableHeaderCell>
            <TableHeaderCell>Last Check</TableHeaderCell>
            <TableHeaderCell>Actions</TableHeaderCell>
          </TableRow>
        </TableHead>
        <TableBody>
          {health.components.map((component) => (
            <TableRow key={component.name}>
              <TableCell>
                <div>
                  <p className="font-medium text-gray-900">{component.name}</p>
                  <p className="text-sm text-gray-500">{component.description}</p>
                </div>
              </TableCell>
              <TableCell>
                <HealthIndicator status={component.status} />
              </TableCell>
              <TableCell>
                <span className={
                  component.responseTime < 100 ? 'text-green-600' :
                  component.responseTime < 500 ? 'text-yellow-600' :
                  'text-red-600'
                }>
                  {component.responseTime}ms
                </span>
              </TableCell>
              <TableCell>
                <span className="text-sm text-gray-500">
                  {new Date(component.lastCheck).toLocaleTimeString()}
                </span>
              </TableCell>
              <TableCell>
                <Button
                  variant="light"
                  size="xs"
                  onClick={() => setShowDetails(
                    showDetails === component.name ? null : component.name
                  )}
                >
                  {showDetails === component.name ? 'Hide' : 'Details'}
                </Button>
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>

      {showDetails && (
        <div className="mt-4 p-4 bg-gray-50 rounded-lg">
          <h4 className="font-medium mb-2">
            {health.components.find(c => c.name === showDetails)?.name} Details
          </h4>
          <pre className="text-xs text-gray-700 overflow-auto">
            {JSON.stringify(
              health.components.find(c => c.name === showDetails)?.details,
              null,
              2
            )}
          </pre>
        </div>
      )}
    </Card>
  );
};

API Service

// src/services/api/admin.ts
import { apiClient } from "./client";
import type { HealthStatus } from "@/types/health";

export const adminApi = {
  async getSystemHealth(): Promise<HealthStatus> {
    const response = await apiClient.get<HealthStatus>("/api/admin/health");
    return response.data;
  },

  async runHealthCheck(component: string): Promise<void> {
    await apiClient.post(`/api/admin/health/${component}/check`);
  },
};

Type Definitions

// src/types/health.ts
export type ComponentStatus = "healthy" | "degraded" | "down";

export interface ComponentHealth {
  name: string;
  description: string;
  status: ComponentStatus;
  responseTime: number;
  lastCheck: string;
  details?: Record<string, any>;
}

export interface HealthStatus {
  overall: ComponentStatus;
  components: ComponentHealth[];
  timestamp: string;
}

Unit Tests

// tests/unit/components/dashboard/SystemHealthIndicators.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { SystemHealthIndicators } from '@/components/dashboard/SystemHealthIndicators';
import * as adminApi from '@/services/api/admin';

vi.mock('@/services/api/admin');

const queryClient = new QueryClient({
  defaultOptions: { queries: { retry: false } },
});

const wrapper = ({ children }: { children: React.ReactNode }) => (
  <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
);

describe('SystemHealthIndicators', () => {
  it('should render all components', async () => {
    const mockHealth = {
      overall: 'healthy' as const,
      components: [
        {
          name: 'API Server',
          description: 'FastAPI backend',
          status: 'healthy' as const,
          responseTime: 45,
          lastCheck: '2025-11-21T10:00:00Z',
        },
        {
          name: 'Database',
          description: 'PostgreSQL',
          status: 'healthy' as const,
          responseTime: 12,
          lastCheck: '2025-11-21T10:00:00Z',
        },
      ],
      timestamp: '2025-11-21T10:00:00Z',
    };

    vi.mocked(adminApi.adminApi.getSystemHealth).mockResolvedValue(mockHealth);

    render(<SystemHealthIndicators />, { wrapper });

    await waitFor(() => {
      expect(screen.getByText('API Server')).toBeInTheDocument();
      expect(screen.getByText('Database')).toBeInTheDocument();
    });
  });

  it('should show details when clicked', async () => {
    const user = userEvent.setup();
    const mockHealth = {
      overall: 'healthy' as const,
      components: [
        {
          name: 'API Server',
          description: 'FastAPI backend',
          status: 'healthy' as const,
          responseTime: 45,
          lastCheck: '2025-11-21T10:00:00Z',
          details: { version: '1.0.0', uptime: 3600 },
        },
      ],
      timestamp: '2025-11-21T10:00:00Z',
    };

    vi.mocked(adminApi.adminApi.getSystemHealth).mockResolvedValue(mockHealth);

    render(<SystemHealthIndicators />, { wrapper });

    await waitFor(() => {
      expect(screen.getByText('API Server')).toBeInTheDocument();
    });

    const detailsButton = screen.getByText('Details');
    await user.click(detailsButton);

    expect(screen.getByText(/version/i)).toBeInTheDocument();
  });
});

2.3 Active Sessions Monitor

Priority: P1 (High) Effort: 4 days Dependencies: WebSocket connection, /api/admin/sessions endpoint

Specification

Real-time table of active user sessions:

• Session ID
• User ID / Anonymous
• Start time
• Duration
• Current activity
• Messages sent
• Token usage
• Actions (view details, terminate)

Visual Design:

• Paginated table with live updates
• Color-coded by activity level
• Expandable rows for session details
• Bulk actions (terminate multiple)

Component Implementation

// src/components/dashboard/ActiveSessionsMonitor.tsx
import { useMemo, useState } from 'react';
import {
  createColumnHelper,
  flexRender,
  getCoreRowModel,
  useReactTable,
  getPaginationRowModel,
  getSortedRowModel,
  type SortingState,
} from '@tanstack/react-table';
import { Card, Badge, Button, TextInput } from '@tremor/react';
import { MagnifyingGlassIcon, XMarkIcon } from '@heroicons/react/24/outline';
import { useWebSocket } from '@/hooks/useWebSocket';
import { formatDuration } from '@/utils/time';
import type { ActiveSession } from '@/types/sessions';

const columnHelper = createColumnHelper<ActiveSession>();

export const ActiveSessionsMonitor: React.FC = () => {
  const [sorting, setSorting] = useState<SortingState>([]);
  const [filter, setFilter] = useState('');
  const [selectedSessions, setSelectedSessions] = useState<Set<string>>(new Set());

  const { data: sessions, emit } = useWebSocket<ActiveSession[]>('active-sessions', {
    reconnect: true,
  });

  const filteredSessions = useMemo(() => {
    if (!sessions) return [];
    if (!filter) return sessions;

    return sessions.filter(
      (s) =>
        s.sessionId.toLowerCase().includes(filter.toLowerCase()) ||
        s.userId?.toLowerCase().includes(filter.toLowerCase()) ||
        s.currentActivity.toLowerCase().includes(filter.toLowerCase())
    );
  }, [sessions, filter]);

  const columns = useMemo(
    () => [
      columnHelper.display({
        id: 'select',
        header: ({ table }) => (
          <input
            type="checkbox"
            checked={table.getIsAllRowsSelected()}
            indeterminate={table.getIsSomeRowsSelected()}
            onChange={table.getToggleAllRowsSelectedHandler()}
            className="rounded border-gray-300"
          />
        ),
        cell: ({ row }) => (
          <input
            type="checkbox"
            checked={row.getIsSelected()}
            onChange={row.getToggleSelectedHandler()}
            className="rounded border-gray-300"
          />
        ),
      }),
      columnHelper.accessor('sessionId', {
        header: 'Session ID',
        cell: (info) => (
          <code className="text-xs bg-gray-100 px-2 py-1 rounded">
            {info.getValue().slice(0, 8)}...
          </code>
        ),
      }),
      columnHelper.accessor('userId', {
        header: 'User',
        cell: (info) => {
          const userId = info.getValue();
          return userId ? (
            <span className="font-medium">{userId}</span>
          ) : (
            <Badge color="gray">Anonymous</Badge>
          );
        },
      }),
      columnHelper.accessor('startTime', {
        header: 'Duration',
        cell: (info) => {
          const duration = Date.now() - new Date(info.getValue()).getTime();
          return <span className="text-sm">{formatDuration(duration)}</span>;
        },
      }),
      columnHelper.accessor('currentActivity', {
        header: 'Activity',
        cell: (info) => {
          const activity = info.getValue();
          const color =
            activity === 'idle' ? 'gray' :
            activity === 'chatting' ? 'green' :
            activity === 'searching' ? 'blue' : 'purple';

          return <Badge color={color}>{activity}</Badge>;
        },
      }),
      columnHelper.accessor('messagesSent', {
        header: 'Messages',
        cell: (info) => (
          <span className="tabular-nums">{info.getValue()}</span>
        ),
      }),
      columnHelper.accessor('tokenUsage', {
        header: 'Tokens',
        cell: (info) => (
          <span className="tabular-nums text-sm">
            {info.getValue().toLocaleString()}
          </span>
        ),
      }),
      columnHelper.display({
        id: 'actions',
        header: 'Actions',
        cell: ({ row }) => (
          <div className="flex gap-2">
            <Button
              variant="light"
              size="xs"
              onClick={() => handleViewDetails(row.original.sessionId)}
            >
              View
            </Button>
            <Button
              variant="light"
              size="xs"
              color="red"
              onClick={() => handleTerminate(row.original.sessionId)}
            >
              End
            </Button>
          </div>
        ),
      }),
    ],
    []
  );

  const table = useReactTable({
    data: filteredSessions,
    columns,
    state: {
      sorting,
    },
    onSortingChange: setSorting,
    getCoreRowModel: getCoreRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    getSortedRowModel: getSortedRowModel(),
    initialState: {
      pagination: {
        pageSize: 10,
      },
    },
  });

  const handleViewDetails = (sessionId: string) => {
    // Open modal or navigate to session details
    console.log('View session:', sessionId);
  };

  const handleTerminate = (sessionId: string) => {
    if (confirm('Are you sure you want to terminate this session?')) {
      emit('terminate-session', { sessionId });
    }
  };

  const handleBulkTerminate = () => {
    const sessionIds = Array.from(selectedSessions);
    if (
      confirm(
        `Are you sure you want to terminate ${sessionIds.length} session(s)?`
      )
    ) {
      emit('terminate-sessions', { sessionIds });
      setSelectedSessions(new Set());
    }
  };

  return (
    <Card>
      <div className="space-y-4">
        <div className="flex items-center justify-between">
          <h3 className="text-lg font-semibold text-gray-900">
            Active Sessions ({filteredSessions.length})
          </h3>
          <div className="flex gap-2">
            {selectedSessions.size > 0 && (
              <Button
                variant="secondary"
                size="xs"
                color="red"
                onClick={handleBulkTerminate}
              >
                Terminate {selectedSessions.size} session(s)
              </Button>
            )}
          </div>
        </div>

        <TextInput
          icon={MagnifyingGlassIcon}
          placeholder="Search sessions..."
          value={filter}
          onChange={(e) => setFilter(e.target.value)}
        />

        <div className="overflow-x-auto">
          <table className="w-full text-sm">
            <thead className="bg-gray-50 border-b">
              {table.getHeaderGroups().map((headerGroup) => (
                <tr key={headerGroup.id}>
                  {headerGroup.headers.map((header) => (
                    <th
                      key={header.id}
                      className="px-4 py-3 text-left font-medium text-gray-700"
                      onClick={header.column.getToggleSortingHandler()}
                      style={{ cursor: header.column.getCanSort() ? 'pointer' : 'default' }}
                    >
                      <div className="flex items-center gap-2">
                        {flexRender(
                          header.column.columnDef.header,
                          header.getContext()
                        )}
                        {header.column.getIsSorted() && (
                          <span>
                            {header.column.getIsSorted() === 'asc' ? '↑' : '↓'}
                          </span>
                        )}
                      </div>
                    </th>
                  ))}
                </tr>
              ))}
            </thead>
            <tbody className="divide-y">
              {table.getRowModel().rows.map((row) => (
                <tr key={row.id} className="hover:bg-gray-50">
                  {row.getVisibleCells().map((cell) => (
                    <td key={cell.id} className="px-4 py-3">
                      {flexRender(cell.column.columnDef.cell, cell.getContext())}
                    </td>
                  ))}
                </tr>
              ))}
            </tbody>
          </table>
        </div>

        {table.getPageCount() > 1 && (
          <div className="flex items-center justify-between">
            <div className="text-sm text-gray-500">
              Page {table.getState().pagination.pageIndex + 1} of{' '}
              {table.getPageCount()}
            </div>
            <div className="flex gap-2">
              <Button
                variant="secondary"
                size="xs"
                onClick={() => table.previousPage()}
                disabled={!table.getCanPreviousPage()}
              >
                Previous
              </Button>
              <Button
                variant="secondary"
                size="xs"
                onClick={() => table.nextPage()}
                disabled={!table.getCanNextPage()}
              >
                Next
              </Button>
            </div>
          </div>
        )}
      </div>
    </Card>
  );
};

Type Definitions

// src/types/sessions.ts
export interface ActiveSession {
  sessionId: string;
  userId: string | null;
  startTime: string;
  currentActivity: "idle" | "chatting" | "searching" | "listening";
  messagesSent: number;
  tokenUsage: number;
  ipAddress?: string;
  userAgent?: string;
}

Utility Functions

// src/utils/time.ts
export function formatDuration(ms: number): string {
  const seconds = Math.floor(ms / 1000);
  const minutes = Math.floor(seconds / 60);
  const hours = Math.floor(minutes / 60);

  if (hours > 0) {
    return `${hours}h ${minutes % 60}m`;
  } else if (minutes > 0) {
    return `${minutes}m ${seconds % 60}s`;
  } else {
    return `${seconds}s`;
  }
}

2.4 API Usage Graphs

Priority: P1 (High) Effort: 3 days Dependencies: /api/admin/usage endpoint

Specification

Interactive charts showing API usage patterns:

• Requests per hour (last 24h)
• Requests by endpoint
• Requests by status code
• Requests by client type

Visual Design:

• Area chart for time series
• Bar chart for endpoint comparison
• Donut chart for status codes
• Time range selector (1h, 6h, 24h, 7d)

Component Implementation

// src/components/dashboard/APIUsageGraphs.tsx
import { useState } from 'react';
import {
  Card,
  Title,
  AreaChart,
  BarChart,
  DonutChart,
  TabGroup,
  TabList,
  Tab,
  TabPanels,
  TabPanel,
  Select,
  SelectItem,
} from '@tremor/react';
import { useQuery } from '@tanstack/react-query';
import { adminApi } from '@/services/api';
import type { APIUsageData } from '@/types/usage';

type TimeRange = '1h' | '6h' | '24h' | '7d' | '30d';

export const APIUsageGraphs: React.FC = () => {
  const [timeRange, setTimeRange] = useState<TimeRange>('24h');

  const { data: usage, isLoading } = useQuery({
    queryKey: ['api-usage', timeRange],
    queryFn: () => adminApi.getAPIUsage(timeRange),
    refetchInterval: 60000, // Refresh every minute
  });

  if (isLoading || !usage) {
    return (
      <Card>
        <div className="animate-pulse space-y-4">
          <div className="h-64 bg-gray-200 rounded"></div>
        </div>
      </Card>
    );
  }

  const timeSeriesData = usage.timeSeries.map((point) => ({
    time: new Date(point.timestamp).toLocaleTimeString(),
    requests: point.count,
    errors: point.errors,
  }));

  const endpointData = usage.byEndpoint.map((item) => ({
    endpoint: item.endpoint,
    requests: item.count,
  }));

  const statusCodeData = usage.byStatusCode.map((item) => ({
    name: `${item.code} (${item.label})`,
    value: item.count,
  }));

  return (
    <Card>
      <div className="space-y-4">
        <div className="flex items-center justify-between">
          <Title>API Usage</Title>
          <Select
            value={timeRange}
            onValueChange={(value) => setTimeRange(value as TimeRange)}
            className="w-32"
          >
            <SelectItem value="1h">Last Hour</SelectItem>
            <SelectItem value="6h">Last 6 Hours</SelectItem>
            <SelectItem value="24h">Last 24 Hours</SelectItem>
            <SelectItem value="7d">Last 7 Days</SelectItem>
            <SelectItem value="30d">Last 30 Days</SelectItem>
          </Select>
        </div>

        <TabGroup>
          <TabList>
            <Tab>Requests Over Time</Tab>
            <Tab>By Endpoint</Tab>
            <Tab>Status Codes</Tab>
          </TabList>
          <TabPanels>
            <TabPanel>
              <AreaChart
                className="h-72 mt-4"
                data={timeSeriesData}
                index="time"
                categories={['requests', 'errors']}
                colors={['blue', 'red']}
                valueFormatter={(value) => `${value} req`}
                showLegend={true}
                showGridLines={true}
                showXAxis={true}
                showYAxis={true}
              />
            </TabPanel>

            <TabPanel>
              <BarChart
                className="h-72 mt-4"
                data={endpointData}
                index="endpoint"
                categories={['requests']}
                colors={['blue']}
                valueFormatter={(value) => `${value} req`}
                showLegend={false}
                showGridLines={true}
                showXAxis={true}
                showYAxis={true}
                layout="vertical"
              />
            </TabPanel>

            <TabPanel>
              <div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-4">
                <DonutChart
                  className="h-72"
                  data={statusCodeData}
                  category="value"
                  index="name"
                  colors={['green', 'blue', 'yellow', 'red']}
                  valueFormatter={(value) => `${value} req`}
                  showLabel={true}
                />
                <div className="space-y-2">
                  <h4 className="font-medium text-gray-900">Status Code Summary</h4>
                  {statusCodeData.map((item) => (
                    <div key={item.name} className="flex justify-between text-sm">
                      <span className="text-gray-600">{item.name}</span>
                      <span className="font-medium">{item.value.toLocaleString()}</span>
                    </div>
                  ))}
                  <div className="pt-2 border-t">
                    <div className="flex justify-between text-sm font-medium">
                      <span>Total Requests</span>
                      <span>
                        {statusCodeData
                          .reduce((sum, item) => sum + item.value, 0)
                          .toLocaleString()}
                      </span>
                    </div>
                  </div>
                </div>
              </div>
            </TabPanel>
          </TabPanels>
        </TabGroup>
      </div>
    </Card>
  );
};