# CLAUDE.md

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

## Development Commands

- **Development server**: `npm run dev` - Starts Next.js development server on http://localhost:3000
- **Build**: `npm run build` - Creates production build
- **Production server**: `npm run start` - Starts production server (requires build first)
- **Lint**: `npm run lint` - Runs Next.js ESLint checks

## High-Level Architecture

This is a Next.js 15 application built with React 19 that creates an interactive map visualization with a custom WebGL timeline component.

### Core Architecture Components

**Map System**:
- Uses MapLibre GL JS for interactive mapping
- `app/map-context.tsx` provides global map state management via React Context
- `components/map-component.tsx` handles map rendering and initialization
- Default map center: Singapore (103.851959, 1.290270) at zoom level 11
- Custom map style from MapTiler API

**Timeline Visualization**:
- `app/timeline.tsx` is a complex WebGL-powered timeline component using custom shaders
- Uses vesica piscis (lens-shaped) geometry rendered via WebGL2
- Custom GLSL shaders in `app/glsl/timeline/` for vertex and fragment processing
- Supports interactive features: dragging, zooming, panning, custom time markers
- Dual-canvas architecture: WebGL canvas for vesica shapes, 2D canvas overlay for UI elements

**UI Framework**:
- Tailwind CSS with Radix UI components
- Theme system with dark/light mode support via `components/theme-provider.tsx`
- shadcn/ui component library in `components/ui/`
- Sidebar layout using `components/ui/sidebar.tsx`

### Key Technical Details

**WebGL Timeline**:
- Renders vesica piscis shapes as timeline markers
- Supports high-DPI displays with proper pixel ratio handling
- Interactive controls for zoom (mouse wheel), pan (drag), and custom time selection
- Real-time shader uniform updates for responsive interactions

**State Management**:
- Map state centralized in `MapProvider` context
- Timeline uses internal React state with refs for performance-critical interactions
- Custom hooks in `hooks/` for map location, zoom, timeline, and mobile detection

**Styling**:
- Tailwind CSS v4 with PostCSS
- Custom animations via `tw-animate-css`
- Component styling via `class-variance-authority` and `clsx`

**Build Configuration**:
- Next.js 15 with App Router
- Custom webpack config for GLSL file loading via `raw-loader`
- TypeScript with strict mode enabled
- Absolute imports using `@/*` path mapping

### File Structure Notes

- `app/` - Next.js App Router pages and components
- `components/` - Reusable React components
- `hooks/` - Custom React hooks
- `lib/` - Utility functions
- `types/` - TypeScript type definitions
- `public/` - Static assets

The application combines modern web mapping with custom WebGL visualization to create an interactive timeline-driven map interface.