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.
📝 Roadmap Highlights
(jenkins)