mmosaic/mosaicmap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
23905d33fd
mosaicmap/CLAUDE.md
Tsuki 23905d33fd update admin page
2025-08-17 20:28:13 +08:00

4.2 KiB
Raw Blame History

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.