https://github.com/crimsonsunset/hh-dashboard

Modern data exploration interface for analyzing LLM response patterns and performance metrics - Built with React, TypeScript, and TanStack Router
https://github.com/crimsonsunset/hh-dashboard

ai-metrics analytics chart-js dashboard data-visualization llm react tanstack-router typescript

Last synced: about 17 hours ago
JSON representation

Modern data exploration interface for analyzing LLM response patterns and performance metrics - Built with React, TypeScript, and TanStack Router

• Host: GitHub
• URL: https://github.com/crimsonsunset/hh-dashboard
• Owner: crimsonsunset
• Created: 2025-10-21T22:22:14.000Z (9 months ago)
• Default Branch: master
• Last Pushed: 2025-11-06T01:01:04.000Z (8 months ago)
• Last Synced: 2025-11-06T03:05:51.637Z (8 months ago)
• Topics: ai-metrics, analytics, chart-js, dashboard, data-visualization, llm, react, tanstack-router, typescript
• Language: TypeScript
• Homepage: https://hh-dashboard.netlify.app/
• Size: 679 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Roadmap: docs/roadmap.md

Awesome Lists containing this project

README

          
# LLM Data Explorer

A modern, type-safe data exploration interface for analyzing LLM response patterns and performance metrics. Built with React, TypeScript, and TanStack Router following clean architecture patterns.

## 🎯 Purpose

Data exploration tool for AI engineers to understand LLM performance through:

- Interactive data loading (small/large datasets)

- Response time visualization with line charts

- Comprehensive data table with virtual scrolling (1000+ rows)

- Model comparison (GPT-4, GPT-3.5, Claude)

- Token usage, cost analysis, and quality metrics

- Error and timeout tracking

## 🚀 Tech Stack

### Core Framework

- **React 19** - Latest React with modern features

- **TypeScript 5.8** - Strict type safety throughout

- **Vite 7** - Lightning-fast build tool and dev server

- **TanStack Router 1.x** - Type-safe file-based routing

### UI & Styling

- **Ant Design 5.x** - Comprehensive component library with built-in theming

- **Recharts 3.x** - Composable charting library for data visualization

### State Management

- **Zustand 5.x** - Lightweight state management for in-memory data and UI state

### Development Tools

- **ESLint 9** - Code quality and consistency

- **TypeScript ESLint** - TypeScript-specific linting rules

## ✨ Features

### Foundation (Complete)

✅ **Type-Safe Architecture** - Strict TypeScript with full inference  

✅ **Clean Code Patterns** - Maintainable, extensible codebase structure  

✅ **Theme System** - Dark/light mode with persistent state  

✅ **Path Aliases** - Clean imports using `@stores`, `@components`, etc.  

✅ **Mock LLM Data** - Small (~5 responses) and large (~1000 responses) datasets  

### Core MVP (In Development)

- **Data Loading Interface** - Load small or large datasets with one click

- **Response Time Chart** - Line chart visualization using Recharts

- **Virtual Scrolling Table** - Ant Design table handling 1000+ rows smoothly

- **Data Reset** - Clear current dataset and load a different one

### Future Enhancements

- **Chart Type Selector** - Toggle between response time, token usage, cost, and quality metrics

- **File Upload** - Drag-and-drop JSON file support with validation  

## 📁 Project Structure

```

hh-dashboard/

├── src/

│   ├── routes/              # File-based routing (TanStack Router)

│   ├── components/          # Reusable React components

│   │   ├── layout/         # Layout components

│   │   ├── charts/         # Chart components

│   │   └── ui/             # UI components

│   ├── stores/             # Zustand state management

│   ├── types/              # TypeScript type definitions

│   ├── services/           # API service layer

│   ├── hooks/              # Custom React hooks

│   ├── utils/              # Helper utilities

│   ├── config/             # Configuration files

│   ├── assets/             # Static assets

│   └── styles/             # Global styles

├── docs/                   # Project documentation

└── public/                 # Public static files

    └── data/               # Mock LLM response data

        ├── long.mock-data.json   # Large dataset (~1000 responses)

        └── short.mock-data.json  # Small dataset (~5 responses)

```

## 📊 Data Structure

LLM response data structure:

```typescript

interface LLMResponse {

  id: string

  timestamp: string

  model: 'gpt-4' | 'gpt-3.5-turbo' | 'claude-3' | string

  prompt_tokens: number

  completion_tokens: number

  total_tokens: number

  response_time_ms: number

  status: 'success' | 'error' | 'timeout'

  cost_usd: number

  temperature: number

  max_tokens: number

  prompt_template: string

  output: string | null

  evaluation_metrics: {

    relevance_score: number

    factual_accuracy: number

    coherence_score: number

    response_quality: number

  } | null

  error: {

    type: string

    message: string

  } | null

}

```

### Path Aliases

All top-level `src` directories use path aliases for clean imports:

```typescript

import { useAppStore } from '@stores/app.store'

import { DashboardLayout } from '@components/layout/dashboard-layout.component'

import { LLMResponse } from '@data/llm.types'

```

### File Naming Convention

- **Components**: `kebab-case.component.tsx` (e.g., `dashboard-layout.component.tsx`)

- **Stores**: `kebab-case.store.ts` (e.g., `app.store.ts`)

- **Types**: `kebab-case.types.ts` (e.g., `llm.types.ts`)

- **Services**: `kebab-case.service.ts` (e.g., `llm.service.ts`)

- **Hooks**: `use-kebab-case.hook.ts` (e.g., `use-llm-data.hook.ts`)

## 🛠️ Getting Started

### Prerequisites

- Node.js 18+ and npm

### Installation

```bash

# Install dependencies

npm install

# Start development server

npm run dev

# Build for production

npm run build

# Preview production build

npm run preview

# Run linter

npm run lint

```

### Development Server

The app runs at `http://localhost:5173` with hot module replacement enabled.

## 🏗️ Architecture Decisions

### State Management Strategy

- **Zustand** for in-memory loaded dataset and UI state (theme, preferences)

- Client-side data loading (no API calls, direct JSON parsing)

- Simple, predictable state flow for data exploration

### Why These Technologies?

**TanStack Router**

- Type-safe routing with full TypeScript inference

- File-based routing for intuitive project structure

- Built-in code splitting for optimal performance

**Zustand**

- Minimal boilerplate compared to Redux

- No context provider needed

- Perfect for in-memory data management

- Tiny bundle size (~1KB)

**Recharts**

- React-first charting library

- Composable, declarative API

- Responsive by default

**Ant Design**

- Enterprise-grade components

- Built-in virtual scrolling for tables

- Excellent theming system

## 📊 Data Flow

1. **User Action** → Click "Load Small Dataset" or "Load Large Dataset"

2. **Data Fetch** → Load JSON file from `/src/data/`

3. **Parse & Validate** → Validate against `LLMResponseData` type

4. **Store Update** → Zustand store receives parsed data

5. **UI Re-render** → Chart and table components display data

6. **Reset** → Clear store, return to loading state

## 🎨 Theming

The app uses Ant Design's built-in theming system with full support for:

- Light and dark color schemes

- Consistent component styling across themes

- Persistent theme preference in Zustand store

Toggle theme via the user menu in the top-right corner.

## 📝 Implementation Approach

### Overview

This project implements a production-ready LLM response data explorer with emphasis on clean architecture, type safety, and performance optimization.

### Technical Approach

1. **State Management Pattern**: Three-layer strategy separating UI state (Zustand), server state (React Query), and URL state (TanStack Router)

2. **Data Loading**: Client-side JSON file loading with React Query for caching and conditional fetching

3. **File Validation**: Three-layer validation system (extension → JSON syntax → schema validation)

4. **Performance**: Virtual scrolling for 1000+ row tables, conditional query fetching, memoized chart data

5. **Error Handling**: User-facing error messages via Ant Design message component with try-catch wrappers

### Key Architectural Decisions

- **TanStack Router**: Type-safe file-based routing with full TypeScript inference

- **Zustand**: Minimal state management (~1KB) for UI preferences and dataset selection

- **React Query**: Server state management with built-in caching and background refetching

- **Ant Design**: Enterprise-grade components with virtual scrolling and theming support

- **Recharts**: React-first declarative charting library

### Implementation Status

- ✅ **Phase 1**: Core data explorer (complete)

- ✅ **Phase 3**: File upload with validation (completed ahead of schedule)

- ⏸️ **Phase 2**: Enhanced visualization (deferred)

## 🎯 Design Principles

This MVP is built as the foundation of a long-term project:

- **Clean Architecture** - Separation of concerns, maintainable patterns

- **Type Safety** - Strict TypeScript, no compromises

- **Simplicity First** - Minimal styling, focus on functionality

- **Performance** - Smooth handling of 1000+ data points

- **Extensibility** - Easy to add new chart types and features

## 📋 Assumptions Made

1. **Client-Side Only**: No backend API required for MVP; all data processing happens client-side

2. **Mock Data Sufficiency**: Two dataset sizes (5 and 1000 responses) are adequate for demonstration

3. **JSON Format**: Custom uploaded files follow the same schema as mock data (`LLMResponseData` type)

4. **Browser Support**: Modern browsers with ES2022 support (Chrome, Firefox, Safari, Edge)

5. **Single User**: No authentication or multi-user considerations needed for MVP

6. **Static Deployment**: App can be deployed to static hosting (Netlify, Vercel, etc.)

7. **Theme Persistence**: Theme preference persists in memory only (session-based, no localStorage)

8. **Virtual Scrolling**: Ant Design's virtual scrolling is sufficient for handling large datasets

## 🚀 Future Improvements

Given more time, the following enhancements would be prioritized:

### Immediate Priorities

- **Wire up Date Selection**: Connect the date picker in the header to filter data by timestamp range

- **Proper URL Routing**: Implement query params for shareable filtered views (`/dashboard?filters=X`)

- **Graph Selector**: Add dropdown to toggle between different chart types (response time, tokens, cost, quality)

### Architecture & Quality

- **Styling System**: Establish design tokens and CSS-in-JS primitives for consistent theming

- **Responsive Design**: Optimize layout for mobile and tablet devices

- **Testing Framework**: Add unit tests (React Testing Library) and E2E tests (Playwright)

### Features

- **Advanced Filtering**: Multi-field filtering (model, status, date range, metrics thresholds)

- **Data Export**: CSV/JSON export functionality

- **Chart Interactions**: Tooltips, zoom, brush selection for detailed analysis

- **Metrics Cards**: Summary statistics at top of dashboard

- **Error Boundaries**: Route-level and component-level error recovery

### Performance

- **Code Splitting**: Dynamic imports for chart components

- **Loading Skeletons**: Replace spinners with skeleton screens

- **Debounced Search**: Add search/filter inputs with debouncing

## 📄 License

This project is private and not licensed for public use.