# CLAUDE.md

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

## Commands

```bash
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**:
1. **adsb.lol** — proxied through `/api/flights` (primary)
2. **OpenSky Network** — direct browser fetch (CORS-enabled)
3. **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