shacn-dashboard/CLAUDE.md

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

# 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.

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.

Data Flow

• All dashboard data comes from getDashboardData() in lib/mock-data.ts
• Data types are defined in types/dashboard.ts
• 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
• 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

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:

import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"

Configured in tsconfig.json.

Chart.js Configuration

• Chart.js is globally registered in lib/chart-config.ts
• 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

Adding new shadcn/ui components:

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 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)

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:

import { IconName } from "lucide-react"

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