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.

Data and Map workspaces include mobile-density CSS for file inputs, dataset action buttons, map toolbar controls, range sliders and empty-map quick actions so narrow screens avoid accidental viewport overflow.

AI Labs uses the same mobile-density baseline for Detection and Segmentation model cards, run forms, QA/result summaries and scroll-safe result tables. This keeps long model ids, tile paths and artifact paths from widening the workbench on phones.

Exports and System provider capabilities now use compact, mobile-safe cards for handoff actions, artifact filters and provider metadata. Long provider limitations, export ids and artifact paths wrap inside their cards instead of widening the workbench.

The right-side inspector also uses mobile-safe metadata and tool panels. Dataset filenames, checksums, bounds, job JSON, raster/vector operation inputs and inspector action groups wrap or scroll within the inspector instead of widening the workbench.

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.
• When the Map workspace has no active result layer, it lists ready vector/GeoJSON datasets as direct quick actions so populated demo projects can jump straight from the empty state to map inspection.
• The Data catalog shows a compact selected/reference/candidate/source summary and scan-friendly badges. Persisted reference datasets are shown as Reference, non-reference vector/GeoJSON layers are shown as QA Candidates for workbench scanning, and raster/other uploads remain Source.
• Dataset cards explain the recommended next action and use compact two-line action buttons for inspect, map, export/QA and metadata refresh. Disabled actions keep a visible reason, such as Vector/GeoJSON only.
• The QA/QC workspace shows candidate/reference handoff cards and resolves persisted quality-check dataset IDs back to dataset names when the datasets are loaded in the current project context.

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.

The QA/QC workspace promotes core metrics into evidence cards before the raw metric list, keeping precision, recall, F1, mean IoU and false positive/negative counts scan-friendly while preserving the persisted raw metrics.

The workbench shell clamps page-level horizontal overflow on mobile while keeping the sidebar and workspace shortcut rows intentionally scrollable. Long QA identifiers and inspector values wrap inside their cards instead of widening the viewport.

The QA/QC result list includes client-side search, status and check-type filters plus a latest-results cap so long-lived demo projects remain scan-friendly without changing the API response shape.

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