Initial public release

docs/FRONTEND_STATE_AND_API_CLIENT.md

@@ -0,0 +1,80 @@
+# Frontend State and API Client Specification
+
+## API client
+
+Create a typed API client under:
+
+```text
+frontend/src/services/api/
+```
+
+Suggested files:
+
+- `client.ts`: fetch wrapper with base URL and error handling.
+- `projects.ts`
+- `areas.ts`
+- `datasets.ts`
+- `analysis.ts`
+- `qa.ts`
+- `exports.ts`
+
+## Error handling
+
+All API errors should be normalized to:
+
+```ts
+type ApiError = {
+  error: string;
+  message: string;
+  details?: unknown;
+  request_id?: string;
+};
+```
+
+## State model
+
+Use TanStack Query for server state:
+
+- projects list
+- project detail
+- datasets list
+- analysis runs
+- QA results
+
+Use local state for UI only:
+
+- selected map layer
+- layer opacity
+- active tool
+- drawn geometry draft
+- side panel state
+
+## Required page states
+
+Every data-driven page must show:
+
+- Loading state.
+- Empty state.
+- Error state.
+- Success state.
+
+## Map state
+
+Map state should not be embedded in every page component. Create reusable hooks/components:
+
+- `MapCanvas`
+- `LayerPanel`
+- `DrawAreaTool`
+- `GeoJsonLayer`
+- `RasterLayerPlaceholder` until real tile serving exists.
+
+## Frontend first-pass priority
+
+Do not build a beautiful but disconnected UI. The first UI must connect to real foundation endpoints:
+
+1. Health check.
+2. Project list/create.
+3. Project detail.
+4. Area creation placeholder/drawn GeoJSON form.
+5. Dataset list.
+6. Capabilities panel.