(jenkins)
76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# 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
|
|
- [ ] 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.
|