# Repository Guidelines

## Project Structure & Module Organization

This repository is a Next.js App Router business system for an Agent-driven drainage-network WebGIS.

- `app/`: route entrypoints only. Keep `page.tsx`, `layout.tsx`, route-level loading/error, and metadata thin.
- `lib/`: shared utilities that are not owned by a feature.
- `features/map/core/`: reusable map UI and generic map helpers only. This layer should not know drainage-network business layer IDs, simulation scenarios, or Agent workflows.
- `features/workbench/`: the drainage-network WebGIS workbench. Put drainage-network sources, layers, simulation overlays, feature adapters, and workbench-specific map interactions here.
- `features/agent/`: Agent-facing task data, panels, and action recommendations. Agent code should produce typed action data instead of mutating the map or UI directly.
- `shared/` (planned): reusable UI, API clients, and cross-feature types once code is reused by multiple features.
- Root markdown files are product/design references and should not be treated as runtime code.

## Build, Test, and Development Commands

Use `pnpm`.

```bash
pnpm dev
```
Starts the local development server at `http://localhost:3000`.

```bash
pnpm build
```
Creates a production Next.js build. Stop `pnpm dev` before running this to avoid concurrent `.next` writes.

```bash
pnpm exec tsc --noEmit
```
Runs TypeScript validation without emitting files.

## Coding Style & Naming Conventions

- Use TypeScript and React function components. Prefer explicit props types over inline anonymous object types for reusable components.
- Use two-space indentation. Keep imports ordered: external packages first, then `@/` aliases, then local relative imports.
- Use kebab-case for filenames and folders: `feature-insight-panel.tsx`, `use-map-selection.ts`, `drainage-network-layers.ts`.
- Use PascalCase for React components and component types: `FeatureInsightPanel`, `MapWorkbenchPage`.
- Use camelCase for variables, functions, object fields, and non-component exports: `selectedFeatureId`, `createWaterNetworkSources`.
- Use `useXxx` for hooks: `useWorkbenchMap`, `usePanelLayout`.
- Use PascalCase type names with clear suffixes: `MapViewState`, `AgentUiResult`, `LayerConfig`, `FeatureInsightProps`.
- Use UPPER_SNAKE_CASE only for stable global constants: `WATER_NETWORK_BOUNDS`, `SOURCE_LAYERS`.
- Use named exports for feature modules. Avoid default exports except for Next.js route files under `app/`.
- Keep MapLibre sources, layers, camera helpers, and interactions outside presentational React components.
- Prefer typed configuration objects for GeoServer layers, Mapbox basemap settings, and Agent actions.

## Code Organization Style

Use thin orchestration components. A page component may compose panels, hooks, and map modules, but should not contain large mock datasets, layer specs, event handlers, and UI markup in one file.

Recommended future pattern:

```txt
features/map/core/
  components/
    base-layers-control.tsx
    scale-line.tsx
    toolbar.tsx
    zoom.tsx
    legend.tsx
    layer-control.tsx
  hooks/
    use-map-camera.ts
    use-layer-visibility.ts
    use-map-selection.ts
  map/
    style.ts
    layer-utils.ts

features/workbench/
  map-workbench-page.tsx
  components/
    workbench-top-bar.tsx
    simulation-dock.tsx
    simulation-result-panel.tsx
  hooks/use-workbench-map.ts
  map/sources.ts
  map/layers.ts
  map/annotation-layers.ts
  state/types.ts

features/agent/
  components/agent-assistant-panel.tsx
  data/agent-task.ts
  types.ts
```

Agent actions should be data, not imperative UI mutations. Let the UI/map state layer validate, preview, confirm, apply, and roll back actions.

Keep the growth boundary clear:
- `features/map/core` owns generic map capabilities such as base layer controls, toolbars, legends, layer controls, camera helpers, and reusable selection primitives.
- `features/workbench` owns drainage-network domain behavior such as pipe, manhole, outfall, and pump-station sources, simulation overlays, feature detail adapters, scenario controls, and business-specific interactions.
- `features/agent` owns task reasoning UI and typed recommendations. It should communicate with the workbench through action objects such as `preview-impact`, `locate-feature`, or `set-layer-visible`.

## Testing Guidelines

There is no formal test suite yet. For now, required checks are:

```bash
pnpm exec tsc --noEmit
pnpm build
```

When tests are added, colocate feature tests near the feature module or place shared integration tests under `tests/`. Name tests after behavior, for example `map-selection.test.ts`.

## Commit & Pull Request Guidelines

This directory currently has no Git history, so no existing commit convention can be inferred. Use concise, imperative commit messages such as:

```txt
Add direct GeoServer MVT sources
Refactor map workbench shell
```

Pull requests should include:
- Summary of user-visible changes.
- Notes on map/data source changes.
- Screenshots for UI changes.
- Verification commands run.

## Security & Configuration Tips

Store local secrets in `.env.local`. Do not commit real tokens. The Mapbox token is read from:

```env
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
```

GeoServer MVT layers are loaded directly from `geoserver.waternetwork.cn`; confirm CORS remains enabled before removing fallbacks or changing hosts.