GEMINI.md - Project Context: Line of Sight 🌍

🚀 Project Overview

Line of Sight is an interactive web application that visualizes great-circle paths around the Earth and identifies major conurbations (cities) along those paths based on user-defined direction and "fuzziness" tolerance.

Architecture

Frontend: React 19 single-page application using Vite 6 for build orchestration and MapLibre GL JS for vector map rendering.
Backend: Node.js 24/Express 5 REST API.
Database: PostgreSQL with the PostGIS extension for geospatial data storage and analysis. Uses kartoza/postgis for robust multi-arch (including ARM64) support.
Infrastructure: Fully containerized using Docker and orchestrated with Docker Compose.

🛠️ Tech Stack

Frontend: React 19, Vite 6, MapLibre GL JS, Axios
Backend: Node.js 24, Express 5, node-postgres (pg) 8.20
Database: PostgreSQL (kartoza/postgis), PostGIS
Testing: Vitest (Frontend), Jest (Backend)
DevOps: Docker, Docker Compose

🚦 Getting Started & Key Commands

Complete System (Docker)

Action	Command
Start Services	`docker-compose up`
Rebuild & Start	`docker-compose up --build`
Stop Services	`docker-compose down`
View Logs	`docker-compose logs -f`
Access DB (psql)	`docker-compose exec postgres psql -U line_of_sight -d line_of_sight`

Backend Development (`/backend`)

Action	Command
Install	`npm install`
Start (Prod)	`npm start`
Start (Dev)	`npm run dev` (Uses nodemon)
Test	`npm test`

Frontend Development (`/frontend`)

Action	Command
Install	`npm install`
Start (Dev)	`npm run start` (Starts Vite)
Build	`npm run build`
Test	`npm run test` (Starts Vitest)

📁 Key File Map

backend/app/server.js: Main Express entry point and API route definitions.
frontend/src/App.js: Primary React component containing map logic and state management.
frontend/src/services/api.js: Axios-based API client for backend communication.
docker/init.sql: Database schema definition including PostGIS extension and seed data.
docker-compose.yml: Service orchestration for the entire stack.

🔧 Development Conventions

Node Versioning: Use nvm to manage Node.js. Run nvm use in the root directory to switch to Node 24 (specified in .nvmrc).
Geospatial Standards: Latitude/Longitude are handled in decimal degrees. Geometry uses SRID 4326 (WGS 84).
API Design: RESTful endpoints returning JSON. The primary endpoint is GET /api/line-of-sight.
Styling: Prefer custom CSS in frontend/src/styles/ over utility-first frameworks like Tailwind for this specific project.
Testing: Tests are located in backend/tests/ and frontend/src/__tests__/. Use vitest (Frontend) and jest (Backend).
Environment: Use .env files for configuration. VITE_API_URL is required for the frontend.

📊 Data Management

The project includes a compressed dataset of ~68,000 cities from Natural Earth.

Action	Command
Import/Refresh Data	`./import-cities.sh`

Note: The script will truncate the cities table and perform a fresh import of the global dataset stored in docker/data/cities.csv.gz.

📝 Roadmap Highlights

Implement real ST_DWithin() PostGIS queries in the backend.
Import full Natural Earth/GeoNames datasets into the cities table.
Transition from 2D MapLibre to a 3D globe visualization.
Optimize line-of-sight calculations for long-distance paths.

3.7 KiB Raw Blame History