CLAUDE.md

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

Commands

npm run dev          # Start dev server (Turbopack)
npm run build        # Production build
npm run start        # Start production server
npm run lint         # ESLint (flat config, ESLint 9)

No test framework is configured.

Architecture

Aeris is a Next.js 16 App Router application for real-time 3D flight tracking, built with React 19, TypeScript (strict), and Tailwind CSS v4. Deployed on Vercel.

Rendering stack

MapLibre GL JS renders the base map (CARTO Dark Matter tiles)
Deck.gl 9 overlays WebGL layers on top: IconLayer (aircraft), PathLayer (trails), ScenegraphLayer (14 3D GLB models served from Cloudinary CDN)
Altitude drives both z-displacement (Math.max(altitude * 5, 200) meters) and color (11-stop RGB gradient)
Motion (Framer Motion v12) handles UI animations with spring physics

Data flow

Flight data uses a 3-tier fallback with circuit breaker:

adsb.lol — proxied through /api/flights (primary)
OpenSky Network — direct browser fetch (CORS-enabled)
Airplanes.live — override only

Polling is adaptive: 10s normally, backs off to 5 min on rate limits. Pauses when tab is hidden (Page Visibility API).

Key source layout

src/app/api/ — 8 proxy routes (flights, ATC audio, weather/METAR, aircraft photos, airspace tiles, radar tiles). All external API calls go through these proxies for CORS and SSRF protection.
src/components/flight-tracker.tsx — Main orchestrator: manages state, camera modes, layers, and UI composition.
src/components/map/ — MapLibre context, Deck.gl layer builders, camera controllers (orbit/FPV/globe), animation helpers with Catmull-Rom spline smoothing.
src/components/ui/ — UI panels (control panel, flight card, ATC panel, FPV HUD, etc.). Uses Radix UI primitives, cmdk for search, Sonner for toasts.
src/hooks/ — Data fetching hooks (use-flights, use-flight-track, use-trail-history), settings context with localStorage persistence, ATC stream management.
src/lib/ — API clients, trail processing (cleanup, stitching, spline interpolation), large static datasets (airports 1.3MB, ATC feeds 200KB, airline logos), GPU memory monitoring.

State management

React hooks + context only. Settings persist to localStorage via use-settings.tsx. URL params enable deep linking (?city=IATA, ?fpv=ICAO24). SSR hydration uses useSyncExternalStore.

Trail system

Per-aircraft trail history with 100-point accumulation buffer, Catmull-Rom spline smoothing, and grid-snapped deduplication. Configurable distance (12–100 points) and thickness (0.5–8 px).

Style conventions

Conventional commits: feat:, fix:, refactor:, etc.
Path alias: @/* maps to ./src/*
OKLCH color system via CSS custom properties in globals.css
Dark-first design with next-themes
No server-side secrets required; env vars are optional (NEXT_PUBLIC_GA_ID)

Build notes

next.config.ts transpiles Deck.gl and Luma.gl packages
CSP headers and aggressive caching on /models (immutable, 1-year max-age)
License: AGPL-3.0

3.2 KiB Raw Blame History Unescape Escape