Skip to content

CLAUDE.md

Latest commit

 

History

History
238 lines (194 loc) · 7.91 KB

CLAUDE.md

File metadata and controls

238 lines (194 loc) · 7.91 KB

CLAUDE.md

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

Project Overview

RPDB (Roadway Pavement Database) Frontend is a Next.js 16 application for visualizing and managing Texas highway pavement data. The application features interactive maps (ArcGIS and Leaflet), data visualization charts, mobile-responsive layouts, and admin tools for managing pavement sections and survey data.

Tech Stack:

  • Next.js 16 (App Router, Static Export)
  • TypeScript
  • TailwindCSS + Radix UI components
  • ArcGIS Maps SDK + Leaflet for mapping
  • Chart.js, Plotly, D3 for visualizations
  • React Context for state management

Development Commands

Running the Application

# Development (LOCAL deployment)
npm run dev

# Production build and preview
npm run build
npm start

# Local build and preview
npm run build-dev
npm run start-dev

# Linting
npm run lint

# Deploy to GitHub Pages
npm run deploy

Python Data Processing Scripts

The scripts/ directory contains Python utilities for processing pavement data:

# Install dependencies first
pip install -r scripts/requirements.txt

# Convert Excel to JSON
python scripts/convert_excel_to_json.py

# Generate highway/county averages
python scripts/hw_cnty_avg.py
python scripts/hw_dist_avg.py

# Convert PMIS data to GeoJSON
python scripts/pmis_to_geo_line.py
python scripts/pmis_to_geo_line_by_year.py

Architecture

Route Structure (App Router)

src/app/
├── (app)/                          # Protected routes requiring auth
│   ├── ProtectedLayout.tsx         # Auth wrapper with JWT refresh
│   ├── page.tsx                    # Main map page (ArcGIS)
│   ├── admin/                      # Admin tools
│   ├── level_one_sections/         # Section management
│   ├── special_sections/[category] # Dynamic category routes
│   ├── experimental_sections/[category]
│   ├── forensic-evaluations/
│   ├── general/
│   │   ├── lane-miles/
│   │   ├── pmis/
│   │   │   ├── condition-analysis/
│   │   │   └── highway-heatmaps
│   │   └── traffic-data/
│   └── specifications/             # TxDOT standards/manuals
└── (auth)/                         # Public auth routes
    ├── login/
    ├── register/
    └── activate/

Component Organization

src/
├──components/
│   ├── chart/               # Chart components (Chart.js, custom)
│   │   ├── HighwaySegmentChart.tsx
│   │   ├── MiniSegmentChart.tsx
│   │   ├── ScoreGauge.tsx
│   │   └── ...
│   ├── map/                 # Leaflet map components
│   ├── map-arcgis/          # ArcGIS map components
│   │   └── MapExplorerModal.tsx
│   ├── mobile/              # Mobile-specific layouts
│   ├── nav/                 # Navigation components
│   ├── section/             # Section data management
│   ├── highway-heatmaps/    # PMIS heat map visualizations
│   └── ui/                  # Radix UI component wrappers
├── constants
├── lib
└── hooks

State Management

React Context providers in src/context/:

  • GlobalLoadingContext - Global loading state
  • MapContext - Shared map state (selected highway, county)
  • ModalContext - Modal visibility state
  • SectionContext - Section data management
  • ThemeContext - Theme preferences

API Integration

  • Backend URL: https://txrpdb-backend.azurewebsites.net
  • Proxy Routes: Defined in src/config.ts (route, routeDownload, routeUploadContent)
  • API Service: src/services/rpdbApiService.ts (currently in mock mode - set mockMode = false when backend is ready)
  • Data Fetching: Uses src/lib/fetchJsonData.ts for static JSON files from Azure blob storage

Authentication System

  • JWT-based auth with automatic token refresh (60s before expiry)
  • Guest mode available via localStorage
  • Protected routes wrapped in ProtectedLayout.tsx
  • Auth utilities: src/lib/auth.ts (isLoggedIn(), isGuest(), clearAuth())
  • Role-based menu access via SIDENAV_ITEMS in src/components/nav/constants.ts

Mobile Responsiveness

The application features a specialized mobile layout (src/components/mobile/) activated at breakpoints < 768px:

  • Swipeable metric cards with touch gesture support
  • Horizontal metric selector header
  • Mini chart previews (MiniSegmentChart)
  • Full-screen chart views with overlay modals
  • See MOBILE_ARCHITECTURE.md for detailed mobile layout flow

Key Mobile Components:

  • MobileLayout.tsx - Main mobile container with swipe logic
  • Card.tsx - Highway/county metric cards
  • MiniSegmentChart.tsx - Deferred rendering chart previews

Data Processing

  • PMIS Data: Highway pavement metrics loaded from CSV files (hw_cnty_avg.csv)
  • GeoJSON: Highway geometry loaded from Azure blob storage
  • Caching: PMIS year data cached via src/lib/pmisYearCache.ts
  • Helpers: src/lib/data-helpers.ts for data transformations

Key Configuration Files

next.config.mjs

  • Static export (output: 'export')
  • Dynamic basePath and assetPrefix based on NEXT_PUBLIC_DEPLOYMENT env var
  • GitHub Pages deployment support with version-based paths
  • Turbopack enabled (Next.js 16 default)

src/config.ts

Environment-aware configuration:

  • NEXT_PUBLIC_DEPLOYMENT: "LOCAL" or "PRODUCTION"
  • routePublic: Base path for static assets (GitHub Pages compatible)

TypeScript

Path alias configured: @/* → ./src/*

Important Patterns

ArcGIS Integration

ArcGIS components must be client-side only ('use client'). Import ArcGIS modules carefully:

import MapView from '@arcgis/core/views/MapView'
import FeatureLayer from '@arcgis/core/layers/FeatureLayer'

Data Loading Pattern

Pages use consistent loading pattern with GlobalLoadingContext:

const { setLoading } = useGlobalLoading()
useEffect(() => {
  setLoading(true)
  // Load data...
  setLoading(false)
}, [setLoading])

CSV Data Processing

Highway data flows: CSV → processedData → segmentDataByHighway → Components

  • Process in parent component
  • Pass via callbacks (onDataProcessed, onSegmentDataReady)
  • Cache segment maps for performance

Modal Management

Modals use controlled state pattern:

const [modalOpen, setModalOpen] = useState(false)
const [modalInfo, setModalInfo] = useState({ highway, county, viewType })

Testing Mobile UI

# Start dev server
npm run dev

# In browser DevTools:
# 1. Toggle device toolbar (Ctrl+Shift+M / Cmd+Shift+M)
# 2. Select mobile device (iPhone 12 Pro, etc.)
# 3. Enable touch simulation
# 4. Test swipe gestures on metric selector

Deployment

The app is configured for static export to GitHub Pages:

  1. Build: npm run build (sets NEXT_PUBLIC_DEPLOYMENT=PRODUCTION)
  2. Deploy: npm run deploy (pushes out/ directory to gh-pages branch)
  3. Access via: https://{username}.github.io/{repo-name}/

Base path is automatically prefixed in production mode.

Critical Implementation Notes

  1. Always use client-side rendering for:

    • ArcGIS components
    • Components accessing window or localStorage
    • Interactive map features

  2. Performance optimizations in place:

    • React.memo on Card/TableRow components
    • useMemo for expensive data transformations
    • useCallback for stable event handlers
    • Dynamic imports for heavy components (maps, charts)
    • Deferred rendering in MiniSegmentChart

  3. TypeScript strict mode enabled - all components must be properly typed

  4. Path Resolution:

    • Use @/ alias for imports (e.g., @/components, @/lib)
    • Static assets use routePublic prefix from @/config

  5. Backend API Service is in mock mode. To enable real API:

    • Set mockMode = false in src/services/rpdbApiService.ts
    • Ensure Azure backend is running and accessible