line-of-sight/GEMINI.md

# 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.