# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Package Manager
- **Always use pnpm** for all package management operations
- Do NOT use npm or yarn - this project exclusively uses pnpm

## Development Commands

```bash
# Install dependencies
pnpm install

# Start development server (http://localhost:3000)
pnpm run dev

# Create production build
pnpm run build

# Start production server
pnpm start

# Run linter
pnpm run lint
```

## Tech Stack & Key Libraries

- **Next.js 14** with App Router (not Pages Router)
- **TypeScript** with strict mode enabled
- **Tailwind CSS v4** with custom theme configuration
- **shadcn/ui** components (New York style variant)
- **Chart.js** via react-chartjs-2 for data visualization
- **next-themes** for dark/light theme management
- **Lucide React** for icons

## Architecture Overview

### Provider Hierarchy
The app uses nested providers in this order (outer to inner):
1. `ThemeProvider` - Manages dark/light theme state
2. `SidebarProvider` - Manages sidebar state (open/collapsed)

Both wrap all page content in [app/layout.tsx](app/layout.tsx:1).

### Layout Structure
The dashboard uses a sidebar + inset layout pattern:
- `<AppSidebar />` - Collapsible navigation sidebar
- `<SidebarInset>` - Main content area containing:
  - `<Header />` - Top header with search and theme toggle
  - Page content (dashboard components)

This structure is defined in [app/page.tsx](app/page.tsx:1).

### Data Flow
- All dashboard data comes from `getDashboardData()` in [lib/mock-data.ts](lib/mock-data.ts)
- Data types are defined in [types/dashboard.ts](types/dashboard.ts:1)
- Data is fetched at the page level and passed down as props

### Component Organization

```
components/
├── ui/              # shadcn/ui components (auto-generated, don't edit manually)
├── layout/          # Layout components (sidebar, header, nav)
├── dashboard/       # Dashboard-specific components (cards, tables, tabs)
├── charts/          # Chart wrapper components
└── theme-provider.tsx
```

### Theming System

The app uses a CSS variable-based theming system:
- **Colors**: Defined using OKLCH color space in [app/globals.css](app/globals.css:1)
- **Variants**: Light mode (`:root`) and dark mode (`.dark` class)
- **Theme switching**: Managed by `next-themes` via the `ThemeProvider`
- **Chart colors**: Dynamic colors that respond to theme changes via `getChartColors()` in [lib/chart-config.ts](lib/chart-config.ts:1)

To modify theme colors, edit the CSS variables in `app/globals.css` under `:root` (light) and `.dark` (dark theme).

### Path Aliases

TypeScript path alias `@/*` maps to the root directory:
```typescript
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"
```

Configured in [tsconfig.json](tsconfig.json:21).

### Chart.js Configuration

- Chart.js is globally registered in [lib/chart-config.ts](lib/chart-config.ts:1)
- Import this file before using any chart components
- Charts automatically adapt colors based on current theme
- Use `getChartColors(theme)` to get theme-aware color palette

## shadcn/ui Configuration

- Style variant: `new-york`
- Base color: `neutral`
- Uses CSS variables for theming
- Configuration in [components.json](components.json:1)

**Adding new shadcn/ui components:**
```bash
pnpm dlx shadcn@latest add <component-name>
```

Components are added to `components/ui/` and should not be manually edited (use composition instead).

## TypeScript Notes

- Path alias: `@/*` points to root directory
- Strict mode enabled
- JSX runtime: `react-jsx` (no need to import React)
- Target: ES2017

## Styling Patterns

- Use `cn()` utility from [lib/utils.ts](lib/utils.ts:1) to merge Tailwind classes
- Custom scrollbar styling via `.scrollbar-thin` utility class
- Responsive breakpoints: `md:` (768px), `lg:` (1024px)
- Grid layouts for dashboard components (see [app/page.tsx](app/page.tsx:25))

## Client vs Server Components

- Most components are Server Components by default
- Add `"use client"` directive only when needed:
  - Theme-related components (using `useTheme`)
  - Chart components (using Chart.js)
  - Interactive components with hooks (useState, useEffect)
  - shadcn/ui components (most require "use client")

## Important Patterns

### Component Composition
When creating new dashboard components, follow the established pattern:
1. Define TypeScript interface in `types/dashboard.ts`
2. Accept props with proper typing
3. Use shadcn/ui Card component as container
4. Apply consistent spacing and layout

### Adding New Charts
1. Create data structure in `types/dashboard.ts`
2. Add mock data to `lib/mock-data.ts`
3. Create chart wrapper in `components/charts/` or `components/dashboard/`
4. Use `getChartColors(theme)` for theme-aware styling
5. Mark component with `"use client"`

### Icon Usage
Use Lucide React icons:
```typescript
import { IconName } from "lucide-react"
```

Icons are passed as string identifiers in metric cards and dynamically resolved in the component.