docs: audit links, glossary T0-T4, readability pass
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify simulator (pull_request) Failing after 4s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify simulator (pull_request) Failing after 4s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
Extend glossary with storage floors, source of truth, and linkable anchors. Fix broken links, pose frame drift, rsync/offload wording, and README tone. Add docs/improvement audit records and live demo links in design journey.
This commit is contained in:
@@ -9,15 +9,15 @@ graph LR
|
||||
subgraph dev [3 — Dev and simulation]
|
||||
SIM["virtual drone fleet<br/>(simulator, Compose)"]
|
||||
LAP["engineer laptop<br/>Dev Container"]
|
||||
SLICE["T4: data slices"]
|
||||
SLICE["[T4](00-glossary.md#t4--dev): data slices"]
|
||||
end
|
||||
subgraph fleet [1 — Fleet, in flight]
|
||||
D1["drone: Compose data plane<br/>T0 hot + T1 NVMe + T2 MinIO"]
|
||||
D1["drone: Compose data plane<br/>[T0](00-glossary.md#t0--hot) hot + [T1](00-glossary.md#t1--warm) NVMe + [T2](00-glossary.md#t2--shared) MinIO"]
|
||||
D2["drone …"]
|
||||
end
|
||||
subgraph ground [2 — Ground, on-prem]
|
||||
DOCK["base station docks"]
|
||||
DWH["T3 warehouse<br/>object store + Parquet/DuckDB"]
|
||||
DWH["[T3](00-glossary.md#t3--warehouse) warehouse<br/>object store + Parquet/DuckDB"]
|
||||
K3S["k3s: CI runners, registry mirror,<br/>sim farm, dashboards"]
|
||||
TRAIN["model training (out of scope)<br/>reads T3, ships weights"]
|
||||
end
|
||||
@@ -34,7 +34,7 @@ graph LR
|
||||
## 1 — Fleet infrastructure (on the drones)
|
||||
|
||||
- Docker Compose under systemd; the full stack from [02 — Architecture](02-architecture.md).
|
||||
- Storage floors T0–T2. Nothing here requires ground contact during a mission.
|
||||
- Storage floors [T0–T2](00-glossary.md#t0--hot). Nothing here requires ground contact during a mission.
|
||||
- Receives new software only while docked, from the registry mirror, pinned by the fleet release manifest.
|
||||
|
||||
## 2 — Ground infrastructure (on-prem)
|
||||
@@ -43,7 +43,7 @@ The permanent installation. This **is** allowed to be a cluster — links are wi
|
||||
|
||||
| Component | Runs on | Role |
|
||||
| --- | --- | --- |
|
||||
| **Warehouse (T3)** | Object store (MinIO or equivalent) + Parquet | Every flight of every drone; the system's long-term memory |
|
||||
| **Warehouse ([T3](00-glossary.md#t3--warehouse))** | Object store (MinIO or equivalent) + Parquet | Every flight of every drone; the system's [source of truth](00-glossary.md#source-of-truth) and long-term memory |
|
||||
| **Base station docks** | Bare metal | Wired offload + integrity audit + drone provisioning ([03](03-data-platform.md), [05](05-network-security.md)) |
|
||||
| **Registry mirror** | k3s | In-air-gap container registry + artifact storage; the only software source drones ever see |
|
||||
| **CI runners** | k3s | Multi-arch builds, tests, scans ([11](11-cicd-delivery.md)) |
|
||||
@@ -60,7 +60,7 @@ The environment engineers live in daily — and deliberately the first thing to
|
||||
- **No debug API** ([04](04-swarm-sync.md)): bench access to a drone's data goes through the same read-only SQL-over-SSH wrapper the peers use in flight — same permissions, same statement gate, same columnar output. Debugging exercises the production path instead of a parallel one, so the query channel is regression-tested every working day for free.
|
||||
- **The virtual drone fleet** ([`simulator/`](../simulator/)) runs the *identical* data plane: same writer, same partitioning, same sealing, same broadcast schema. `DRONE_COUNT=10 docker compose up` is a swarm on a laptop.
|
||||
- **Scenarios are reproducible by seed:** route shapes, sensor noise, drone dropouts, link losses are all parameterized — a bug report is a seed + config, not a war story.
|
||||
- **T4 data slices**: a thin tool pulls partition subsets from T3 (`flight=X, drone=Y, hour=Z`) for local work — layout-identical, so every query and pipeline runs unmodified.
|
||||
- **[T4](00-glossary.md#t4--dev) data slices**: a thin tool pulls partition subsets from [T3](00-glossary.md#t3--warehouse) (`flight=X, drone=Y, hour=Z`) for local work — layout-identical, so every query and pipeline runs unmodified.
|
||||
- The same simulator images scale out on the ground k3s farm for CI regression runs: every merge request replays canonical scenarios and asserts on the resulting Parquet output (row counts, coverage, staleness budgets).
|
||||
|
||||
## IaC boundaries
|
||||
@@ -74,13 +74,13 @@ Infrastructure as code follows the same discipline as the data plane: each tool
|
||||
| Ongoing ground configuration | **Flux** ([`infra/gitops/`](../infra/gitops/)) | Policy labels, dashboard bundles, offload knobs — reconciled from git without reprovisioning PVCs. Drones stay on the fleet manifest, not GitOps. |
|
||||
| On-board runtime | **Compose bundle from the fleet release manifest** | Terraform is deliberately *not* on the drone: there is no API server to reconcile against mid-flight, and the release manifest already gives atomic, versioned, rollback-able delivery ([11](11-cicd-delivery.md)). |
|
||||
|
||||
Shared local data paths (same layout everywhere): **`var/t1/`** (live lake, T1) and **`var/t3/`** (warehouse, T3). Compose, k3d, and DuckDB on the host all read the same Parquet tree.
|
||||
Shared local data paths (same layout everywhere): **`var/t1/`** (live lake, [T1](00-glossary.md#t1--warm)) and **`var/t3/`** (warehouse, [T3](00-glossary.md#t3--warehouse)). Compose, k3d, and DuckDB on the host all read the same Parquet tree.
|
||||
|
||||
Two Terraform modules, two states, one deliberate split: [`sim-env`](../infra/terraform/sim-env/) (the disposable virtual fleet) and [`ground`](../infra/terraform/ground/) (the warehouse that must survive every `destroy` of the fleet). They never share a lifecycle.
|
||||
|
||||
### k3d: the ground segment as an executable miniature
|
||||
|
||||
`ansible-playbook infra/ansible/sim-cluster.yml` creates a local k3d cluster (k3s in Docker — the same distribution as the real ground segment) and `terraform apply` populates it: virtual drones as StatefulSet replicas over a shared Parquet lake, the exporter/Prometheus/Grafana stack, the data-plane explorer, MinIO, and the T1→T3 offload CronJob. The whole diagram at the top of this page runs on one workstation, and the prototype's **live mode** renders real drone positions straight from the explorer's read-only SQL API.
|
||||
`ansible-playbook infra/ansible/sim-cluster.yml` creates a local k3d cluster (k3s in Docker — the same distribution as the real ground segment) and `terraform apply` populates it: virtual drones as StatefulSet replicas over a shared Parquet lake, the exporter/Prometheus/Grafana stack, the data-plane explorer, MinIO, and the [T1](00-glossary.md#t1--warm)→[T3](00-glossary.md#t3--warehouse) offload CronJob. The sim CronJob uses `cp -ru` plus `mc mirror` as a shortcut; production dock [offload](00-glossary.md#offload) uses rsync or `mc mirror` with checksum audit ([03](03-data-platform.md)). The whole diagram at the top of this page runs on one workstation, and the prototype's **live mode** renders real drone positions straight from the explorer's read-only SQL API.
|
||||
|
||||
### Next fidelity step: microVMs
|
||||
|
||||
@@ -90,7 +90,7 @@ The k3d fleet shares one kernel and one network namespace tree — good enough t
|
||||
|
||||
| Operation | What it costs with one layout everywhere |
|
||||
| --- | --- |
|
||||
| Flight offload | `mc mirror` / `rsync` + audit — no transform step |
|
||||
| Flight offload | `rsync` / `mc mirror` + audit — no transform step ([03](03-data-platform.md)) |
|
||||
| Debugging a field issue | Pull the flight slice, replay locally, same queries |
|
||||
| Validating a pipeline change | Run simulator, diff Parquet outputs |
|
||||
| Training data prep | Read T3 directly, no export pipeline |
|
||||
|
||||
Reference in New Issue
Block a user