93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
# 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
|
|
|
|
**Note**: No test framework is currently configured in this project.
|
|
|
|
## 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`
|
|
|
|
**Admin System**:
|
|
- Comprehensive admin interface in `app/admin/` with dashboard, analytics, user management, and content editor
|
|
- Admin pages include dynamic configuration system and navigation components
|
|
- Uses both Apollo Client and GraphQL Request for data fetching
|
|
|
|
**Data Layer**:
|
|
- GraphQL API integration using Apollo Client and GraphQL Request
|
|
- Backend communication via `/api/bff` endpoint (configured in `lib/gr-client.ts`)
|
|
- Page-based content management with block-based architecture
|
|
- Authentication support with JWT tokens
|
|
|
|
### 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` (see `next.config.ts`)
|
|
- TypeScript with strict mode enabled
|
|
- Absolute imports using `@/*` path mapping
|
|
|
|
**GraphQL Integration**:
|
|
- Uses both Apollo Client (`@apollo/client`) and GraphQL Request (`graphql-request`) for different use cases
|
|
- Page content fetching via `lib/fetchers.ts` with support for authentication
|
|
- Block-based content architecture supporting TextBlock, ChartBlock, SettingsBlock, and HeroBlock types
|
|
- Environment variables: `GRAPHQL_BACKEND_URL` and `NEXTAUTH_URL`
|
|
|
|
### File Structure Notes
|
|
|
|
- `app/` - Next.js App Router pages and components
|
|
- `app/admin/` - Complete admin interface with dashboard, analytics, users, and content editor
|
|
- `app/glsl/timeline/` - Custom GLSL shaders for WebGL timeline rendering
|
|
- `components/` - Reusable React components
|
|
- `components/ui/` - shadcn/ui component library
|
|
- `hooks/` - Custom React hooks for map, timeline, and mobile detection
|
|
- `lib/` - Utility functions including GraphQL clients and data fetchers
|
|
- `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, complemented by a full-featured admin system for content management. |