92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# 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.
|