geointel/docs/FRONTEND_STATE_CONTRACTS.md

Frontend State Contracts

Global API State

Every API-backed component must support:

• idle
• loading
• success
• empty
• error
• refreshing

Route State Pattern

Each route must render a usable state for:

• no project selected
• data loading
• data loaded
• API error
• permission/configuration warning

Map State

Map state includes:

• active project
• active area
• active base layer
• visible layers
• selected feature
• drawing mode
• measurement mode

Analysis State

Analysis state includes:

• selected dataset
• selected area
• selected model
• parameters
• current run
• run history
• output layers

Layer State

Layer object:

interface MapLayerState {
  id: string;
  name: string;
  type: 'raster' | 'vector' | 'detections' | 'segmentations' | 'qaqc';
  visible: boolean;
  opacity: number;
  styleId?: string;
  sourceId: string;
}

Empty State Copy

Use precise empty states:

• Projects: "Create your first GeoIntel project to start an analysis."
• Areas: "Draw or import an area before running geospatial processing."
• Datasets: "Upload a raster/vector dataset or connect a data source."
• Detections: "Run object detection to create geospatial AI outputs."
• QA/QC: "Select an AI run and reference layer to calculate quality metrics."