278 lines
14 KiB
Markdown
278 lines
14 KiB
Markdown
# GeoIntel Frontend (Sprint 4)
|
|
|
|
React + TypeScript + MapLibre foundation for project/area/dataset workflow.
|
|
|
|
The workbench is intentionally map-first: `MapWorkspace` is promoted above the dense workflow grid so GIS context stays visible before lower-detail provider, AI, QA and export panels. Long workflow panels are scroll-contained by CSS rather than stretching every grid row.
|
|
|
|
## 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.
|
|
|
|
## 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`
|