geointel/docs/13-implementation-traps/FRONTEND_STATE_RULES.md

Frontend State Rules

GeoIntel frontend must be predictable, API-driven and resistant to partial build regressions.

State Layers

Use three state categories:

1. Server state: projects, datasets, areas, analysis runs, metrics, exports.
2. UI state: selected tab, open panel, layer opacity, map camera.
3. Draft state: unsaved polygon, upload form, threshold slider before run.

Server state must be loaded through API client functions. Do not duplicate server truth in Zustand except as cached references managed by query tooling.

Required Page States

Every data-driven page must render:

• initial loading
• empty state
• error state
• ready state
• processing state when jobs exist

Map State

Map layer state must include:

• id
• name
• source
• visibility
• opacity
• style
• legend label
• feature count if known

Analysis Run State

Analysis run UI must display:

• status
• started_at
• completed_at when available
• parameters
• model mode if AI-related
• output layers
• metrics
• errors if failed

Form Validation

Client validation improves UX but must not replace backend validation.

Navigation

The navigation should preserve the mental model:

• Projects
• Workspace
• Map
• Datasets
• Raster
• Vector
• Detection
• Segmentation
• QA/QC
• Exports

Do not hide core modules behind unrelated dashboard labels.