79 lines
3.0 KiB
Markdown
79 lines
3.0 KiB
Markdown
# 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
KAPTAN_GROUND_SUITE_HOST=127.0.0.1 KAPTAN_GROUND_SUITE_PORT=4173 nix run .#ground-suite
|
||
```
|
||
|
||
Inside the development shell:
|
||
|
||
```sh
|
||
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.
|