line-of-sight/CLAUDE.md

# CLAUDE.md

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

## What This Project Is

**Line of Sight** is a geospatial web app that draws a great-circle line from a user-selected point on Earth in a chosen direction, then finds all cities along that path. It includes a flight-over animation that speeds up 20x over water and slows to normal speed over land.

## Commands

### Docker (preferred workflow)

```bash
docker-compose up --build       # Start all services (frontend :3050, backend :3051, postgres)
docker-compose down             # Stop all services
docker-compose logs -f          # View logs

# Run tests inside containers
docker-compose exec backend npm test
docker-compose exec frontend npm test -- --run
docker-compose exec frontend npm run test:e2e
```

### Local development (without Docker)

```bash
# Backend
cd backend && npm run dev       # Nodemon dev server on :3051

# Frontend
cd frontend && npm run start    # Vite dev server on :3050
```

### Tests

```bash
# Backend unit tests (Jest + Supertest)
cd backend && npm test

# Frontend unit tests (Vitest)
cd frontend && npm test          # Watch mode
cd frontend && npm test -- --run # Single run (CI mode)

# E2E tests (Playwright)
cd frontend && npm run test:e2e

# Seed the database with GeoNames city data
cd backend && npm run seed-data
```

### Build

```bash
cd frontend && npm run build    # Vite production build → frontend/build/
```

## Architecture

This is a monorepo with three services orchestrated by Docker Compose:

```
frontend/  → React 19 + Vite 6 SPA (MapLibre GL, Turf.js, Axios)
backend/   → Node 24 + Express 5 REST API
docker/    → PostgreSQL + PostGIS initialization
```

### Data flow

1. User clicks map → sets start point (lat/lon)
2. User selects direction (0–360°) and tolerance (km radius)
3. Frontend calls `GET /api/line-of-sight?lat=&lon=&direction=&tolerance=`
4. Backend generates 80 path points along a great-circle arc (up to 20,000 km)
5. For each point, a PostGIS `ST_DWithin()` query finds cities within tolerance
6. Backend also checks whether each point is over land (500 km radius land check)
7. Response includes line coordinates with per-point water flags and matching cities
8. Frontend renders the path on a 3D globe map and shows city markers

### Backend: `backend/app/server.js`

Single-file Express app. Key internals:
- `calculateDestination()` — Haversine formula for great-circle destination points
- `GET /api/line-of-sight` — main endpoint: path generation + PostGIS city lookup
- `GET /api/health` — health check
- Returns up to 200 cities ordered by position along the line

### Frontend: `frontend/src/App.jsx`

Single large React component (~687 lines) managing all state and map logic:
- MapLibre GL map with 3D globe projection and terrain/sky effects
- Direction slider drives a live preview line before the user commits
- After "Show Line of Sight", map locks (prevents moving start point)
- Flight animation uses Turf.js to interpolate positions along the path; speed is 1× over land, 20× over water with smooth acceleration (0.005 step), predictive look-ahead of 2000 km
- New cities are fetched every 2000 km during flight via the same API
- Three map styles: light, dark, satellite (Esri tiles)

### Database

PostGIS `cities` table with a GIST index on `geom GEOGRAPHY(POINT, 4326)`. All coordinates use WGS84 / SRID 4326. The init SQL seeds 10 major cities; the `seed-data` script imports from GeoNames for a fuller dataset.

## Conventions

- **Geospatial**: WGS84 / SRID 4326 everywhere; PostGIS `GEOGRAPHY` type for distance queries
- **API**: RESTful; query params for `GET /api/line-of-sight`; env var `VITE_API_URL` (frontend) or `DATABASE_URL` (backend)
- **Styling**: Plain CSS files in `frontend/src/styles/` — no CSS framework
- **Tests**: Backend mocks the `pg` Pool; frontend mocks MapLibre GL and the API service. E2E tests use Playwright with a mock API response

## CI

Gitea workflow (`.gitea/workflows/test.yml`) runs on push/PR to `main`:
1. **backend-test** — `npm ci && npm test`
2. **frontend-test** — `npm ci && npm test -- --run`
3. **e2e-test** — uses `mcr.microsoft.com/playwright:v1.50.1` container