refactor: organize supply frontend structure
This commit is contained in:
@@ -1,37 +1,169 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Project Structure
|
||||
## Scope
|
||||
|
||||
This is a Vite React single-page WebGIS Agent workbench. Runtime TypeScript lives
|
||||
under `src/`.
|
||||
This repository contains the Vite and React single-page frontend for the
|
||||
Agent-driven supply-network WebGIS. Runtime TypeScript lives under `src/`.
|
||||
The application uses React 19, TypeScript, Tailwind CSS, MapLibre GL, deck.gl,
|
||||
SWR, Vitest, and Playwright.
|
||||
|
||||
- `src/app/`: application shell and providers.
|
||||
- `src/features/agent/`: controlled Agent UI protocol, schemas, renderer, and views.
|
||||
- `src/features/map/`: WebGIS map shell and future MapLibre/deck.gl integrations.
|
||||
- `src/shared/`: reusable UI, config, styles, and utilities.
|
||||
- `src/mocks/`: MSW handlers and fixtures for backend-independent development.
|
||||
- `src/test/`: Vitest setup.
|
||||
- `server/`: same-origin Edge TTS adapter used by Vite and the production container.
|
||||
Keep this project browser-first. Do not add Next.js APIs, `"use client"`
|
||||
directives, or general backend-for-frontend routes. Agent reasoning and tool
|
||||
execution belong in `next-tjwater-agent`.
|
||||
|
||||
## Commands
|
||||
## Source Layout
|
||||
|
||||
Use `pnpm`.
|
||||
- `src/app/` owns application startup, providers, and shell composition.
|
||||
- `src/features/workbench/` owns supply sources, layers, SCADA overlays,
|
||||
scenarios, feature adapters, GeoServer configuration, and workbench
|
||||
interactions.
|
||||
- `src/features/agent/` owns Agent protocol clients, sessions, typed frontend
|
||||
actions, validated UI envelopes, recommendations, and Agent panels.
|
||||
- `src/features/map/core/` owns domain-neutral map controls, legends, notices,
|
||||
and reusable map presentation primitives.
|
||||
- `src/shared/` owns reusable UI, AI presentation elements, runtime
|
||||
configuration, and feature-independent utilities.
|
||||
- `src/mocks/` owns MSW handlers and fixtures.
|
||||
- `src/test/` owns shared Vitest setup and repository-wide invariant tests.
|
||||
- `tests/browser/` owns product-level Playwright regressions.
|
||||
- `public/` contains static supply-network and SCADA assets plus the
|
||||
runtime-config placeholder.
|
||||
- `server/` contains the same-origin Edge TTS adapter used by Vite and the
|
||||
production container.
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
pnpm build
|
||||
pnpm typecheck
|
||||
pnpm lint
|
||||
pnpm test
|
||||
pnpm test:browser
|
||||
Do not recreate a catch-all `src/lib/` directory. Put feature-independent
|
||||
helpers in `src/shared/`; put supply-network and GeoServer logic in the
|
||||
owning `workbench` module.
|
||||
|
||||
Do not create empty placeholder directories. Add a directory with its first
|
||||
source file.
|
||||
|
||||
## Dependency Direction and Public APIs
|
||||
|
||||
Keep dependencies moving toward generic code:
|
||||
|
||||
```text
|
||||
app -> workbench, map/core, shared
|
||||
workbench -> agent, map/core, shared
|
||||
agent -> map/core, shared
|
||||
map/core -> shared
|
||||
shared -> external packages only
|
||||
```
|
||||
|
||||
## Coding Notes
|
||||
- `src/app` may import the `workbench` and `map/core` public APIs plus
|
||||
shared startup configuration.
|
||||
- `workbench` may import `agent`, `map/core`, and `shared`.
|
||||
- `agent` may import generic `map/core` presentation helpers and `shared`,
|
||||
but it must not import `workbench`.
|
||||
- `map/core` must not know supply layer IDs, SCADA models, workbench state, or
|
||||
Agent workflows.
|
||||
- `shared` must not import from `app`, `features`, or `mocks`.
|
||||
- Runtime feature code must not import from `app` or `mocks`.
|
||||
|
||||
Use TypeScript and React function components. Prefer explicit exported types at
|
||||
module boundaries. Keep Agent dynamic UI rendering schema-driven: Agent output
|
||||
must be validated before it reaches React components.
|
||||
Use a feature's `index.ts` as its public API for cross-feature imports. Add an
|
||||
intentional public export when another feature needs a symbol. Use relative
|
||||
imports within the same feature. Do not introduce cross-feature deep imports
|
||||
or barrels for private implementation files.
|
||||
|
||||
Do not add Next.js APIs or general BFF routes to this frontend. Agent behavior
|
||||
belongs in the Agent service; the local `server/` exception is limited to the
|
||||
same-origin Edge TTS network adapter.
|
||||
## Component and Module Design
|
||||
|
||||
- Use TypeScript and React function components. Export explicit types at
|
||||
feature and adapter 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 application and page components focused on composition. Extract state,
|
||||
effects, network flows, resize behavior, and map orchestration into focused
|
||||
hooks, controllers, or child components.
|
||||
- Keep MapLibre sources, layers, camera helpers, feature queries, and event
|
||||
handling outside presentational components. Map mutations belong in typed
|
||||
controllers or map helpers.
|
||||
- Keep Agent rendering schema-driven. Validate Agent output before it reaches
|
||||
React. Model map actions as typed data that can be previewed, confirmed,
|
||||
applied, and rolled back.
|
||||
- Keep reusable UI free of supply-network terminology and workflow state. The
|
||||
owning feature decides business behavior.
|
||||
- Prefer one source of truth. Search for an existing utility, config wrapper,
|
||||
style token, or domain type before adding another.
|
||||
|
||||
## Supply-Domain Boundary
|
||||
|
||||
This repository models a supply network. Pipes, junctions, valves, reservoirs,
|
||||
tanks, pumps, pressure, flow, water age, demand, isolation, and continuity of
|
||||
supply belong in `workbench`.
|
||||
|
||||
Do not introduce drainage-network layer IDs, assets, terminology, export
|
||||
filenames, configuration prefixes, fixtures, or operating assumptions.
|
||||
Drainage concepts such as conduits, orifices, outfalls, manholes, sewage,
|
||||
stormwater, and overflow risk do not belong here.
|
||||
|
||||
`next-tjwater-drainage-frontend` may be consulted for generic architecture
|
||||
patterns only. Never copy its domain constants, source catalogs, map styles,
|
||||
icons, mocks, product copy, environment variables, or defaults into this
|
||||
repository. The supply-domain invariant test in
|
||||
`src/test/supply-domain.test.ts` must remain green.
|
||||
|
||||
## Runtime and Server Boundaries
|
||||
|
||||
Browser configuration is injected through `/runtime-config.js` and validated
|
||||
in `src/shared/config/env.ts`. Use `TJWATER_*` variables. Do not add
|
||||
`DRAINAGE_*`, `VITE_*`, or legacy `NEXT_PUBLIC_*` browser configuration.
|
||||
|
||||
Browser-safe GeoServer reads may happen directly when CORS is enabled. Agent
|
||||
requests go to the configured Agent service. The local `server/` exception is
|
||||
limited to the same-origin Edge TTS network adapter; do not turn it into a
|
||||
general API layer or add free-form proxy routes.
|
||||
|
||||
## Tests
|
||||
|
||||
- Co-locate focused Vitest tests with the module under test using `*.test.ts`
|
||||
or `*.test.tsx`.
|
||||
- Put repository-wide invariants and shared setup in `src/test/`.
|
||||
- Put new product and interaction Playwright tests in `tests/browser/`.
|
||||
`src/app/app.e2e.ts` is retained migration coverage, not a location to copy.
|
||||
- Name tests after behavior. Cover pure map calculations, adapters, protocol
|
||||
validation, and state transitions without requiring a browser when possible.
|
||||
- Add focused Playwright coverage for visible behavior, responsive layout,
|
||||
runtime configuration, keyboard and pointer interaction, or map integration.
|
||||
|
||||
## Commands and Verification
|
||||
|
||||
Use `pnpm` from this repository.
|
||||
|
||||
```bash
|
||||
pnpm dev # start Vite on http://127.0.0.1:5173
|
||||
pnpm lint # run ESLint
|
||||
pnpm typecheck # run TypeScript without emitting files
|
||||
pnpm test # run Vitest
|
||||
pnpm test:browser # run Playwright
|
||||
pnpm build # typecheck, build the SPA, and bundle the TTS adapter
|
||||
```
|
||||
|
||||
Match verification to the change:
|
||||
|
||||
- Documentation-only changes: run `git diff --check` and verify referenced
|
||||
paths and commands.
|
||||
- TypeScript logic or component changes: run `pnpm lint`, `pnpm typecheck`,
|
||||
and `pnpm test`.
|
||||
- Visible UI, responsive, configuration, or map interaction changes: also run
|
||||
focused `pnpm test:browser` coverage.
|
||||
- Dependency, Vite, container, runtime integration, or release changes: also
|
||||
run `pnpm build`.
|
||||
|
||||
Do not report a check as passing unless it ran in the current worktree. If a
|
||||
required browser or external service is unavailable, report the skipped layer
|
||||
and reason.
|
||||
|
||||
## Security and Repository Hygiene
|
||||
|
||||
Do not commit secrets, `.env.local`, generated `dist/` or `dist-server/`,
|
||||
dependency folders, Playwright artifacts, session dumps, tokens, or logs. Keep
|
||||
server-only targets and credentials in untracked environment files.
|
||||
|
||||
Treat Agent output, UI envelopes, feature identifiers, URLs, and runtime
|
||||
configuration as untrusted input. Validate at system boundaries, keep
|
||||
credentials out of browser-visible values, and use typed adapters instead of
|
||||
free-form command or request construction.
|
||||
|
||||
Preserve unrelated work in a dirty checkout. Do not clean, reset, move, or
|
||||
rewrite user changes while completing a scoped task.
|
||||
|
||||
Reference in New Issue
Block a user