66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# 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
|