Initial public release

docs/13-implementation-traps/FRONTEND_STATE_RULES.md

@@ -0,0 +1,70 @@
+# 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.