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.

pnpm dev

Starts the local development server at http://localhost:3000.

pnpm build

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

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:

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:

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:

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:

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.

5.3 KiB Raw Blame History