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.

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:

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.

3.3 KiB Raw Permalink Blame History