Update application ports to 3050 and enhance Playwright tests with WebGL mock

2026-04-01 11:04:16 +01:00
parent cac76a2f69
commit 228032c913
11 changed files with 278 additions and 19 deletions
@@ -0,0 +1,70 @@
+# Copilot Instructions for line-of-sight
+
+## Purpose
+This repository is a full-stack geospatial app:
+- `frontend/`: React + Vite + MapLibre UI
+- `backend/`: Express API with PostGIS queries
+- `docker/` and `docker-compose.yml`: local orchestration and DB initialization
+
+Prefer small, focused changes that keep frontend/backend contracts stable.
+
+## First Commands to Know
+Use these commands first when validating changes.
+
+### Docker-first workflow (preferred)
+- Start stack: `docker-compose up --build`
+- Stop stack: `docker-compose down`
+- Backend tests: `docker-compose exec backend npm test`
+- Frontend unit tests: `docker-compose exec frontend npm test -- --run`
+- Frontend E2E tests: `docker-compose exec frontend npm run test:e2e`
+- Seed geodata: `docker-compose exec backend npm run seed-data`
+
+### Local workflow (without Docker)
+- Root Node version: `nvm use` (uses `.nvmrc`, currently Node 24)
+- Backend dev: `cd backend && npm install && npm run dev`
+- Frontend dev: `cd frontend && npm install && npm run start`
+
+## Architecture and Boundaries
+- Backend API entrypoint: `backend/app/server.js`
+  - Defines `GET /api/line-of-sight` and `GET /api/health`
+  - Performs destination/path generation and PostGIS querying
+- Frontend app entrypoint: `frontend/src/App.jsx`
+  - Owns map lifecycle, animation, and UI state
+  - Calls backend via `frontend/src/services/api.js`
+- Database bootstrap: `docker/init.sql`
+  - Enables PostGIS and creates `cities` with spatial index
+
+When changing behavior, prefer backend geospatial logic over duplicating calculations in the frontend.
+
+## Project Conventions
+- Keep geospatial coordinates in WGS84 (`SRID 4326`) and preserve existing lat/lon parameter naming.
+- Keep API responses JSON-compatible and backward compatible unless explicitly requested.
+- Keep frontend styles in `frontend/src/styles/` (project uses custom CSS, not utility CSS frameworks).
+- Avoid broad refactors in `App.jsx` unless task requires it; map lifecycle and refs are tightly coupled.
+
+## Testing Expectations
+- Backend tests live in `backend/tests/` and use Jest + Supertest.
+- Frontend unit tests live in `frontend/src/__tests__/` and use Vitest + Testing Library.
+- E2E tests live in `frontend/e2e/` and use Playwright.
+- For feature changes:
+  - Run the closest unit tests first.
+  - Run E2E tests when user flows or map interactions are changed.
+
+## Common Pitfalls
+- PostGIS must be available before backend geospatial endpoints are exercised.
+- `docker-compose.yml` pins Postgres service to `linux/arm64`; this can affect non-ARM hosts.
+- Data import script (`backend/scripts/import_cities.js`) depends on `wget` and `unzip` availability.
+- `README.md` contains roadmap/history notes; trust current scripts/config in source files first.
+
+## CI Notes
+CI config is in `.gitea/workflows/test.yml`.
+- Backend and frontend tests run on Node 24.
+- Frontend unit tests run with `npm test -- --run`.
+- E2E runs in Playwright container.
+
+## Link, Do Not Duplicate
+For detailed setup and product context, reference:
+- `README.md`
+- `GEMINI.md`
+
+Keep this file focused on actionable agent guidance and repo-specific guardrails.