# Claude Dashboard

A comprehensive cost and usage analysis platform for tracking Claude Code usage and spending across our organization.

**Deployment:** https://dev-internal-spa-test.dev.theorchard.io

---

## Overview

Claude Dashboard combines data from three Anthropic Admin APIs to provide unified insights into:

- **API Usage Costs** - Token-based cost deduction from Claude usage
- **Developer Analytics** - Claude Code sessions, commits, PRs, and code modifications
- **Direct Cost Reporting** - Workspace-level cost breakdowns
- **Cost Analysis** - Comparative analysis between different data sources
- **Spending Projections** - Forecasting and trend analysis

---

## Architecture

The application is split into two main components:

### Frontend (React SPA)

**Stack:** React 18 + TypeScript + Vite + Orchard Suite Components

**Structure:**
```
frontend/src/
├── pages/          # Route components (home, usage, analytics, projections, etc.)
├── components/     # Reusable UI (charts, tables, metrics cards)
├── data/           # Data loading, React Context, static JSON files
├── types/          # TypeScript schemas with Zod validation
└── styles/         # SCSS stylesheets
```

**Features:**
- 9+ routes for different data views and analysis tools
- Interactive charts using Highcharts
- Centralized data loading via React Context
- Type-safe data validation with Zod schemas
- Responsive UI with Orchard Suite components

**Data Flow:**
1. Static JSON files loaded from `src/data/`
2. Zod schemas validate and transform data
3. React Context provides data to all components
4. Pages consume data with no prop drilling

### API (Python Data Pipeline)

**Stack:** Python 3.13+ with stdlib only (no external dependencies)

**Structure:**
```
api/src/
├── usage/          # Usage app - token-based cost deduction (dollars)
├── cost_report/    # Cost Report app - direct costs from API (cents)
├── analytics/      # Analytics app - Claude Code activity metrics
├── shared/         # Reusable utilities (api_client, date_utils)
└── debug/          # Reconciliation and diagnostic tools
```

**Three Data-Source Applications (plus debug tools):**

1. **Usage** (`src/usage/`) - Fetches raw usage data and deduces costs from token counts
   - Main: `cost_analyzer.py` (with time grouping)
   - Output: `output/usage/costs.json` (cost unit: dollars)

2. **Cost Report** (`src/cost_report/`) - Fetches direct cost data from Cost Report API
   - Main: `cost_report_analyzer.py`
   - Output: `output/cost_report/cost_report.json`
   - Note: All costs in cents (e.g., 177730.05 = $1777.30 USD)

3. **Analytics** (`src/analytics/`) - Fetches Claude Code activity metrics per user per day
   - Main: `analytics_analyzer.py`
   - Output: `output/analytics/analytics.json`

Debug tools (`src/debug/`) reconcile the three sources. The processed JSON is then consumed by the React frontend (no HTML is generated server-side; a former HTML-dashboard app has been removed).

**Data Pipeline:**
```
Anthropic Admin APIs → Python Fetchers → raw JSON → processed JSON → frontend/src/data → React SPA
```

---

## Quick Start

### Frontend Development

```bash
cd frontend
pnpm install
pnpm start          # Dev server at localhost:8080
pnpm build          # Production build
pnpm typecheck      # TypeScript validation
```

### Backend Data Pipeline

```bash
cd api
make install-dev            # Setup Python environment
make update                 # Fetch all sources, regenerate, compare, sync to frontend, upload to S3 (interactive)

# Or run individual steps:
make fetch-usage-full       # Fetch usage data
make fetch-analytics-full   # Fetch analytics
make fetch-cost-report-full # Fetch cost report
make sync-frontend          # Copy processed JSON to frontend/src/data/
```

**Environment Variables:**
- `CLAUDE_ADMIN_KEY` - Anthropic Admin API key (required for backend)

---

## Key Features

### Data Views
- **Home Dashboard** - Overview with key metrics and trends
- **Usage API View** - Detailed cost breakdown by user and API key
- **Analytics API View** - Developer activity and code metrics
- **Cost Report View** - Workspace-level cost analysis
- **User Details** - Individual user cost and activity breakdown
- **Projections** - Spending forecasts and trend analysis

### Analysis Tools
- **Cost Differences** - Compare data across three API sources
- **Time Series Charts** - Track usage and costs over time
- **Breakdown Tables** - Drill down by period, user, workspace
- **Metrics Grids** - Summary statistics and KPIs

### Debug Tools
- `debug_cost_api.py` - Investigate specific user data
- `compare_costs.py` - Compare all three data sources
- `verify_differences.py` - Analyze cost discrepancies
- `anonymize_costs.py` - Remove PII for sharing

---

## Technology Stack

| Layer | Technologies |
|-------|-------------|
| **Frontend** | React 18, TypeScript 5, Vite, React Router v5 |
| **UI Components** | Orchard Suite Components, Highcharts |
| **Validation** | Zod (runtime schema validation) |
| **Backend** | Python 3.13+, stdlib only |
| **Code Quality** | Biome (frontend), Ruff + MyPy (backend) |
| **Build Tools** | Vite (frontend), Hatchling + UV (backend) |
| **Task Automation** | Makefile (6 modular sub-makefiles) |

---

## Project Structure

```
.
├── frontend/           # React SPA
│   ├── src/
│   │   ├── pages/     # Route components
│   │   ├── components/# Reusable UI
│   │   ├── data/      # Data layer + JSON files
│   │   └── types/     # TypeScript schemas
│   └── package.json
│
├── api/               # Python data pipeline
│   ├── src/
│   │   ├── usage/        # Usage app (deduced costs)
│   │   ├── cost_report/  # Cost Report app (direct costs, cents)
│   │   ├── analytics/    # Analytics app (Claude Code activity)
│   │   ├── debug/        # Reconciliation / diagnostics
│   │   └── shared/       # api_client, date_utils
│   ├── output/       # Generated raw + processed JSON (gitignored)
│   └── Makefile
│
└── README.md
```

---

## Deployment

**Frontend:** Deployed as private SPA at https://dev-internal-spa-test.dev.theorchard.io

**Data Updates:** Backend scripts run periodically to fetch fresh data from Anthropic APIs and regenerate JSON files.

**Authentication:** Configured for internal access only.

---

## Development Workflow

1. **Fetch Data** - Run backend scripts to pull latest data from APIs
2. **Sync to Frontend** - Copy generated JSON files to `frontend/src/data/`
3. **Develop UI** - Build components and pages using React + Suite
4. **Validate** - TypeScript + Zod ensure type safety
5. **Test Locally** - Run dev server and verify changes
6. **Deploy** - Build production bundle and deploy to staging/prod

---

## Contributing

- **Frontend:** Follow Biome formatting (4-space indent, single quotes)
- **Backend:** Follow Ruff + MyPy (200-char lines, strict types)
- **Git Hooks:** Husky + lint-staged enforce formatting on commit
- **Type Safety:** All code must pass TypeScript/MyPy checks