mosaicmap/CLAUDE.md

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.