# GeoIntel Frontend (Sprint 4)

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

The workbench now uses a task-based shell instead of a single long panel stack. `App.tsx` still owns shared orchestration state, but the UI is organized into Overview, Data, Map, QA/QC, AI Labs, Exports and System workspaces with a persistent top context bar and right-side dataset inspector.

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

## Sprint 20 additions

- Area API responses now include persisted AOI GeoJSON for map display.
- The Map Workbench renders the selected project area as a dedicated MapLibre GeoJSON layer.
- Added area visibility and opacity controls alongside the existing active vector/result layer controls.
- Area list items can select which AOI is shown on the map.

## Sprint 21 additions

- Loading the explicit demo workflow now opens the candidate vector fixture dataset directly, so the Map Workbench shows the demo vector layer without an extra manual dataset click.
- The demo/export verification script now checks connected V1 state: area GeoJSON, fixture datasets, vector FeatureCollection content, vector feature summary, persisted QA/QC metrics and export downloads through the frontend proxy.

## Sprint 22 additions

- Added a compact V1 Workbench status strip above the main panels.
- The strip summarizes existing connected state for project, AOI, datasets, active map layer, persisted QA/QC results and exports.
- It suggests the next operator action based on missing V1 loop state without calling new APIs or adding backend behavior.
- The status strip is implemented in `src/components/WorkbenchStatusStrip.tsx` and remains driven by `App.tsx` orchestration state.
- MapLibre source/layer updates now wait for style readiness to avoid runtime blank-screen failures during first render.

## Sprint 23 additions

- Project report HTML exports now include a V1 readiness summary.
- The report summary covers project, AOI, datasets, QA/QC, exports and known limitations.
- Export Center behavior is unchanged; the richer handoff content is produced by the existing project report export action.

## Sprint 26 maintainability updates

- Detection workflow orchestration moved from `src/App.tsx` into `src/hooks/useDetectionWorkflow.ts`.
- Segmentation workflow orchestration moved from `src/App.tsx` into `src/hooks/useSegmentationWorkflow.ts`.
- Shared frontend API error formatting now lives in `src/lib/formatError.ts`.
- Detection Lab and Segmentation Lab UI behavior is unchanged; `App.tsx` still wires the same panel props and shared project/map state.

## Sprint 27 maintainability updates

- Export Center orchestration moved from `src/App.tsx` into `src/hooks/useExportWorkflow.ts`.
- QA/QC comparison and persisted quality-check listing moved from `src/App.tsx` into `src/hooks/useQualityWorkflow.ts`.
- Detection and segmentation QA continue to share the same persisted QA/QC refresh path through `loadQualityChecks`.
- Export Center and QA/QC UI behavior is unchanged; `App.tsx` still coordinates selected project, dataset and analysis-run state.

## Sprint 28 maintainability updates

- Dataset selection, upload form state, detail loading, dataset jobs and raster/vector operation orchestration moved from `src/App.tsx` into `src/hooks/useDatasetWorkflow.ts`.
- Project-scoped dataset listing remains in `App.tsx` because it is still part of the shared project/area load boundary.
- Dataset details, raster controls, vector controls and job list behavior are unchanged; the UI still receives the same callbacks and state.

## Sprint 29 maintainability updates

- Dataset upload/list rendering moved into `src/components/datasets/DatasetPanel.tsx`.
- Dataset details and job-list rendering moved into `src/components/datasets/DatasetDetailPanel.tsx`.
- Raster controls and vector controls now live in `src/components/datasets/RasterControls.tsx` and `src/components/datasets/VectorControls.tsx`.
- `App.tsx` still owns cross-module orchestration and passes the same `useDatasetWorkflow` state/actions into these presentational components.

## Sprint 30 maintainability updates

- Persisted QA/QC result rendering moved into `src/components/quality/QualityResultsPanel.tsx`.
- Map layer controls, MapLibre rendering and the feature inspector are now composed by `src/components/map/MapWorkspace.tsx`.
- `App.tsx` still owns selected project, selected area, active layer and inspector state; the extracted components receive the same state and callbacks as props.
- No map behavior, QA/QC API behavior, backend behavior, migrations or product features changed.

## 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.
- Export preview rendering lives in `src/components/exports/ExportPreview.tsx`.
- The Export Center only offers JSON preview for JSON/GeoJSON artifacts; HTML project reports are shown as download-only artifacts.
- Provider capability loading lives in `src/hooks/useProviderCapabilities.ts`.
- Change detection orchestration lives in `src/hooks/useChangeDetectionWorkflow.ts`.
- Derived MapLibre workbench state lives in `src/hooks/useMapWorkspaceState.ts`.
- Project, area and dataset-list loading lives in `src/hooks/useProjectWorkspace.ts`.
- Area fallback selection now lives with the owning workflow hooks: clip-area selection in `useDatasetWorkflow.ts` and map-area selection in `useMapWorkspaceState.ts`.
- Offline demo workflow orchestration lives in `src/hooks/useDemoWorkflow.ts`, because it coordinates project, dataset, map, QA/QC, detection, segmentation and export state after the backend fixture seed.
- Workbench bootstrap and reload effects live in `src/hooks/useWorkbenchBootstrap.ts`, keeping `App.tsx` focused on composing hooks into panels.
- The workbench shell includes a compact command bar, consistent raised/sunken surfaces, structured empty states and scroll-safe AI result tables to keep the V1 workflow usable across desktop and mobile widths.
- The Export Center includes a handoff readiness summary, grouped artifact actions and provenance-rich export cards so report/GeoJSON handoff stays understandable in long-running demo projects.

## Workbench shell refactor

- The primary UI is organized around `workspaceNavItems` in `src/App.tsx`.
- The shell regions are:
  - `workbench-topbar`: active project, AOI, dataset and layer context.
  - `workbench-sidebar`: primary navigation between workflow workspaces.
  - `workbench-main`: one active workflow at a time.
  - `workbench-inspector`: persistent selected dataset details and raster/vector operation controls.
- Existing API calls, hooks, MapLibre rendering and QA/AI/export flows are unchanged.
- Stable navigation test anchors use `data-testid="workspace-nav-{workspace}"`.
- Mobile workbench navigation uses horizontal rails for the primary nav and command bar, avoiding a tall menu stack before the active workspace content.
- The Map workspace shows active layer source/provenance/draw-state context and selected-feature property chips before the raw JSON inspector.

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