(jenkins)
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# 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 :3001, 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 :3001
|
||
|
||
# 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
|