kaptan/ground-suite/README.md

Kaptan Ground Suite

Kaptan Ground Suite is a map-first web workspace for coordinating missions, tasks, groups, roles, and approximately 50 robotic vehicles. This first release is deliberately backed by a deterministic simulation. It does not connect to Kaptan firmware and does not send commands to real vehicles.

Run and verify

From the repository root:

nix run .#ground-suite
nix run .#ground-suite -- test
nix flake check
nix develop .#ground-suite

The server binds to 127.0.0.1:4173 by default, prints its URL, and prints a simulated-data warning. Override only when intentionally exposing the local demo:

KAPTAN_GROUND_SUITE_HOST=127.0.0.1 KAPTAN_GROUND_SUITE_PORT=4173 nix run .#ground-suite

Inside the development shell:

cd ground-suite
npm ci
npm run dev
npm test
npm run test:e2e
npm run check

The application has no remote runtime dependency: the demonstration map, catalog imagery, fonts, simulation, and overlays are local. Catalog imagery is covered by public/assets/vehicle_catalog/LICENSE.md (CC0 1.0).

Operating model

The map is one continuously mounted operations scene. Fleet, queue, events, deployment, commissioning, recovery, layers, and settings are drawers, trays, or overlays; they never replace or remount the map. Strategic, operational, tactical, and engineering detail is driven by the same camera and selection.

Selection, operator-local control groups, authoritative mission groups, and authority leases are separate. Every consequential intent remains a local spatial draft until its immutable targets, authority, energy, link, freshness, constraints, and source status have been reviewed. The fake adapter is the only mutation-capable source and is labelled as simulation throughout the scene.

The typed interaction controller and its mode contract live in src/interaction/controller.ts. It owns selection, lasso/marquee, pan, command intent, formation, annotation, task/safety geometry, measurement, mission points, editing, erasing, and draft undo/redo. The benchmark and composition decisions are recorded in docs/DESIGN_RESET.md.

Primary code boundaries:

• src/core/data-plane/: transport-neutral source, envelope validation, ordering/deduplication, journal, reducers, preview, and command submission.
• src/adapters/fake/: scenario-owned deterministic clock and 50-vehicle source; no UI component imports it.
• src/domain/ and src/projections/: authoritative types and derived selectors.
• src/core/persistence/: versioned local operator preferences only.
• src/adapters/kaptan/ and src/adapters/cerebrum/: explicit future ports; neither claims a live integration.
• src/app/ and src/design-system/: persistent spatial scene, coordinate map, docked workbenches, charts, SVG iconography, and the supplied graphite/navy visual language.
• tests/e2e/visual-compositions.spec.ts: eight deterministic high-fidelity states rendered at 1366×768, 1920×1080, and 3440×1440.

See docs/ for architecture, safety, source behavior, and issue traceability.