# Repository Guidelines

## Project Structure

This repository is a Vite React single-page business system for an Agent-driven
drainage-network WebGIS. Runtime TypeScript lives under `src/`.

- `src/app/`: application shell and providers.
- `src/features/map/core/`: reusable map UI and generic map helpers. This layer
  must not know drainage-network business layer IDs or Agent workflows.
- `src/features/workbench/`: drainage sources, layers, SCADA overlays, feature
  adapters, scenarios, and workbench-specific interactions.
- `src/features/agent/`: Agent protocol, sessions, typed actions, panels, and
  recommendations.
- `src/shared/`: reusable UI, AI elements, runtime configuration, and utilities.
- `src/mocks/`: MSW handlers and fixtures.
- `tests/browser/`: product-specific Playwright regressions.
- `public/`: static drainage and SCADA assets plus the runtime-config placeholder.
- `server/`: same-origin Edge TTS adapter used by Vite and the production container.

Do not add Next.js APIs or general BFF routes. Agent behavior belongs in the
Agent service; the local `server/` exception is limited to the same-origin Edge
TTS network adapter. Browser-safe GeoServer reads may happen directly when CORS
is enabled.

## Commands

Use `pnpm`.

```bash
pnpm dev
pnpm build
pnpm typecheck
pnpm lint
pnpm test
pnpm test:browser
```

The Vite development server listens on `http://127.0.0.1:5173` by default.
`pnpm build` runs TypeScript validation before producing `dist/`.

## Coding Style

- Use TypeScript and React function components with explicit exported types at
  module boundaries.
- Use two-space indentation and kebab-case filenames.
- Use PascalCase for components and types, camelCase for functions and values,
  and `useXxx` for hooks.
- Keep orchestration components thin. Move sources, layers, event handling, and
  feature adapters into focused modules.
- Keep MapLibre sources, layers, camera helpers, and interactions outside
  presentational components.
- Keep Agent rendering schema-driven. Validate Agent output before it reaches
  React, and represent map actions as typed data that can be previewed,
  confirmed, applied, and rolled back.

## Domain Boundaries

- `src/features/map/core` owns generic controls, legends, camera helpers, and
  reusable selection primitives.
- `src/features/workbench` owns conduits, junctions, orifices, outfalls, pumps,
  SCADA sources, simulation overlays, and drainage-specific behavior.
- `src/features/agent` owns task reasoning UI and controlled recommendations.

Do not reintroduce supply-network layer IDs or assets into the drainage config.
GeoServer layer names, workspace defaults, map style tokens, titles, and Agent
copy must remain drainage-specific.

## Verification

Frontend changes should pass:

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

Run focused Playwright tests when changing visible behavior, responsive layout,
runtime configuration, or map interactions. Name tests after behavior.

## Configuration and Security

Browser configuration is injected through `/runtime-config.js` and validated in
`src/shared/config/env.ts`. Use `DRAINAGE_*` variables; legacy `NEXT_PUBLIC_*`
names are not supported.

Do not commit secrets, `.env.local`, generated `dist/`, dependency folders,
Playwright artifacts, tokens, or session dumps. Keep server-only proxy targets
in untracked environment files.