geointel/docs/FRONTEND_STATE_AND_API_CLIENT.md

Frontend State and API Client Specification

API client

Create a typed API client under:

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:

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.