# 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.