geointel/frontend/README.md

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

cd frontend
npm install

Run locally

npm run start

Type check and build

npm run typecheck
npm run build

Dockerized frontend

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