# GeoIntel Frontend (Sprint 4)

React + TypeScript + MapLibre foundation for project/area/dataset workflow.

## Scope implemented
- API client layer (`src/services/api`)
- Project and area list/create flows
- Vector and raster dataset upload + metadata display
- MapLibre map with uploaded feature preview

## Sprint 2 additions
- Dataset manager details now shows:
  - dataset type
  - processing status
  - file size
  - vector feature count
  - vector bounds
  - file metadata (original/stored filename, MIME type, SHA256)
  - raster metadata preview when available
- Vector inspection and raster metadata endpoint support in API client
- Readiness indicator for uploaded datasets

## Sprint 3 additions
- Dataset detail panel now includes:
  - available operations
  - operation run actions (`clip`, `buffer`, `intersect`)
  - linked job list and status details
  - derived dataset navigation from job output
- Raster operation callouts for unavailable processing states
- Vector operation summaries integrated in selected dataset view

## Sprint 4 additions
- Dataset detail panel now includes raster-specific runtime metadata:
  - driver, dimensions, band count, bounds, CRS
  - storage details (`size_bytes`, `checksum_sha256`)
- Added action buttons for raster operations:
  - regenerate/inspect metadata
  - generate preview
  - generate tiles
  - clip by selected area
- Added clear unavailable states for raster ops when backend returns `RASTER_PROCESSING_UNAVAILABLE`
- Added operation/job result visibility for raster runs with derived dataset navigation

## Sprint 5 additions
- Added raster band statistics display in the dataset detail panel (min/max/mean/std/nodata ratio/valid pixel count).
- Added raster reproject workflow in UI (target CRS + resampling) with visible errors for invalid CRS/dependency gaps.
- Added stronger raster tile/clip result context with consistent job status display and derived output links where produced.
- Added tile manifest-aware controls for raster tile generation parameters.

## Sprint 6 additions
- Added spectral index controls in dataset detail panel:
  - NDVI with NIR/Red band inputs
  - NDWI with NIR/Green band inputs
  - NDBI with SWIR/NIR band inputs
- Added job-driven execution for local spectral index operations and result dataset linking.
- Added clear error surfacing for dependency-unavailable index execution (`RASTER_PROCESSING_UNAVAILABLE`).
- Added CRS/bounds/resolution context visibility for raster index source inspection.

## Sprint 7B additions
- Added a lightweight Provider Capabilities panel.
- The panel lists GRB, OSM, manual and fixture provider status, configured state, authority level, supported layers, supported geometry types, query modes and limitation messages.
- GRB and OSM are shown as `not_configured`; the UI does not expose a live import/download action for them.
- Existing dataset, reference and QA/QC UI remains unchanged.

## Sprint 8 additions
- Added a minimal Detection Lab panel.
- The panel lists detection model capabilities and clearly shows configured/not_configured status.
- Users can select a raster dataset, choose a confidence threshold and request a detection run.
- Unavailable model responses are shown honestly with the backend error code/message.
- The UI does not claim real YOLO/PyTorch inference is enabled.

## Sprint 8B additions
- Detection Lab now exposes the `yolo-configured` capability reported by the backend.
- When `yolo-configured` is selected, users can provide an existing raster tile manifest path.
- The UI still does not download models or create fake detections; backend status and error codes remain the source of truth.

## Sprint 8C additions
- Detection Lab now lists detection analysis runs and persisted detections.
- Users can filter detections by class and minimum confidence.
- Selected detection GeoJSON is rendered on the existing MapLibre workbench map.
- Detection QA compares a selected detection run against a reference dataset and displays persisted QA metrics.
- No segmentation UI is introduced in Sprint 8C.

## Sprint 9 additions
- Added a minimal Segmentation Lab panel.
- The panel lists segmentation model capabilities and clearly distinguishes placeholders, fixture/demo mode, SAM placeholder and YOLO-seg placeholder states.
- Users can select a raster dataset, select a configured segmentation model, list segmentation runs and load persisted segmentation results.
- Segmentation results display class, confidence, area, model, tile and mask path fields.
- Selected segmentation GeoJSON is rendered through the existing MapLibre workbench map.
- Segmentation QA compares a selected segmentation run against a reference dataset and displays persisted QA metrics.
- Real SAM/YOLO-seg inference, model downloads and new AI dependencies are not introduced in Sprint 9.

## Sprint 10 maintainability updates
- Split large workbench sections out of `src/App.tsx` without changing UI behavior:
  - `src/components/project/ProjectPanel.tsx`
  - `src/components/project/AreaPanel.tsx`
  - `src/components/providers/ProviderPanel.tsx`
  - `src/components/detection/DetectionLab.tsx`
  - `src/components/segmentation/SegmentationLab.tsx`
- `App.tsx` still owns shared state orchestration and API calls; extracted components receive the same state and callbacks as props.
- Existing MapLibre overlay behavior, dataset/reference flows, Detection Lab flows and Segmentation Lab flows are unchanged.

## Sprint 15 additions

- Added a Projects panel action to load the explicit offline demo workflow.
- The action calls `POST /api/v1/demo/workflow` and refreshes projects, areas, datasets and run lists.
- Demo data is labelled fixture/demo data and does not represent live GRB/OSM data or AI inference.

## Sprint 16 additions

- Added a QA/QC Results panel that lists persisted project quality checks and metric rows.
- The panel calls `GET /api/v1/projects/{project_id}/quality-checks`.
- Demo workflow loading and QA actions refresh the persisted QA/QC result list.

## Sprint 17 additions

- Added an Export Center panel.
- The panel can create persisted exports for:
  - project metadata JSON
  - project report HTML
  - selected vector dataset GeoJSON
  - selected detection run GeoJSON
  - selected segmentation run GeoJSON
- Export records are listed from `GET /api/v1/exports/projects/{project_id}/exports`.
- JSON artifact preview uses `GET /api/v1/exports/{export_id}/content`.
- Artifact downloads use `GET /api/v1/exports/{export_id}/download`.
- The UI does not introduce live provider downloads, a report designer or new AI behavior.
- The HTML report is a lightweight artifact built from persisted project, dataset, QA/QC summary and export history state; it is not a PDF/report designer.

## Sprint 18 additions

- Added a Change Detection panel for comparing two vector datasets in the same project.
- Change Detection uses the backend job envelope and renders added/removed/unchanged GeoJSON on the existing MapLibre workbench map.
- The UI exposes IoU threshold and unchanged-feature inclusion controls.
- The frontend does not infer fake object lifecycle states; it displays only the backend-provided added/removed/unchanged result.

## Sprint 19 additions

- Added V1 Map Workbench controls for the active GeoJSON layer:
  - visibility toggle
  - opacity slider
  - active layer label
  - loaded feature count
- Added click-to-inspect feature properties from the active MapLibre layer.
- Updated the app header to the V1 workbench identity instead of an old sprint label.

## Release hardening updates

- Production builds split application code, React vendor code and MapLibre vendor code into separate chunks.
- The MapLibre chunk is intentionally larger than generic app chunks because it contains the GIS map runtime; the Vite warning threshold is set to keep this known vendor dependency visible without warning on every release build.

## Raster dependency visibility

Raster metadata and raster ops may remain unavailable when backend raster stack is missing. In that case:

- raster uploads are still stored and listed
- status becomes `failed`
- backend returns explicit `RASTER_PROCESSING_UNAVAILABLE` responses for metadata/preview/clip/tile

## Run locally

### Prerequisites

- Node.js 18+

### Install dependencies

```bash
cd frontend
npm install
```

### Run locally

```bash
npm run start
```

### Type check and build

```bash
npm run typecheck
npm run build
```

### Dockerized frontend

```bash
docker compose up --build frontend
```

When using the repository Docker Compose stack, the frontend is published on host port `1202`: `http://localhost:1202`.

The frontend API client uses same-origin requests by default. In Docker Compose, nginx serves the built frontend and reverse proxies `/api` and `/health` to the backend service, so browser clients on LAN hosts do not call their own `localhost:8000`.

## Useful repository scripts

- `bash scripts/frontend_install.sh`
- `bash scripts/frontend_typecheck.sh`
- `bash scripts/frontend_build.sh`
- `bash scripts/frontend_dev.sh`

## Key docs
- `docs/40-build-launch/SPRINT_1_SCOPE_FREEZE.md`
- `docs/API_CONTRACTS.md`
- `docs/REPOSITORY_CONVENTIONS.md`