eSlider
d3ccd6f94e
Add docs/adr/ with a chronological ADR set reconstructed from the project history (no orchestrator, one storage format, derived-state sync, SQL-over-SSH contract, WireGuard beneath SSH, IaC boundaries, non-root image, runtime data paths, bounded lake scans), an index README, and a template. Distinguish repo-local ADRs from ecosystem-wide ASRs. Expand AGENTS.md with a decision-records section and a runtime/operations guide (service URLs, rebuild workflow, CPU budget knobs). Reference the ADRs from README, CONTRIBUTING, and the affected design docs, and add an open question for T1 partition pruning.
81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# AGENTS.md
|
|
|
|
Rules for anyone (human or tooling) contributing to this repository.
|
|
|
|
## Hard rules
|
|
|
|
1. **English only.** All documentation, code, comments, commit messages, and file names are written in English.
|
|
2. **No identifying references.** Never mention names of people, companies, organizations, or locations anywhere in this repository — not in docs, code, comments, or git history. This is a generic, self-contained design proposal for an on-prem data platform for autonomous drone swarms.
|
|
3. **Clean git history.** Commit messages must never reference AI assistants, code generation tools, or editors. No `Co-authored-by` trailers pointing to tools, no "Generated with ..." lines. Conventional commit format (`feat:`, `fix:`, `docs:`, `refactor:`).
|
|
4. **Push target.** The only remote is `origin` → `git.produktor.io`. Never mirror this repository anywhere else.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
docs/ Design documentation (Markdown + Mermaid)
|
|
simulator/ Virtual drone fleet — Python data generator (Parquet/DuckDB pipeline)
|
|
prototype/ 2D swarm visualization — React + TypeScript (Vite)
|
|
infra/ Ansible host prep, Terraform workloads, Flux GitOps overlays
|
|
var/t1/ Shared T1 live lake (gitignored runtime data)
|
|
var/t3/ Shared T3 warehouse (gitignored runtime data)
|
|
```
|
|
|
|
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and TDD requirements.
|
|
|
|
## Conventions
|
|
|
|
- Markdown: ATX headings, fenced code blocks with language tags, pipe tables.
|
|
- Python: PEP 8, type hints, pure functions where possible, no unnecessary classes.
|
|
- TypeScript: strict mode, functional components and hooks, no extra UI libraries.
|
|
- YAML: 2-space indent.
|
|
- Diagrams: Mermaid inside Markdown.
|
|
|
|
## Decision records
|
|
|
|
Significant architectural decisions are recorded chronologically as **ADRs** in
|
|
[`docs/adr/`](docs/adr/) — one immutable file per decision, in the
|
|
Status / Context / Options / Decision / Consequences format. Start from
|
|
[`docs/adr/README.md`](docs/adr/README.md).
|
|
|
|
- **ADR** = a point-in-time decision for *this* repo → `docs/adr/`.
|
|
- **ASR** = a standing, ecosystem-wide standard (Go-first, secrets, layout) →
|
|
lives in the `inventar` repo, **not** here.
|
|
|
|
When a change alters a boundary, contract, or trade-off, add an ADR (copy
|
|
[`docs/adr/TEMPLATE.md`](docs/adr/TEMPLATE.md), take the next number, update the
|
|
index) and cross-link it from the affected design doc. A later reversal gets a
|
|
new ADR that supersedes the old one — never edit an Accepted record.
|
|
|
|
## Runtime & operations (sim environment)
|
|
|
|
The k3d ground miniature is `swarm-sim`. Services are exposed as NodePorts:
|
|
|
|
| Service | URL |
|
|
| --- | --- |
|
|
| Explorer (T1 live lake) | `http://localhost:30088` |
|
|
| Warehouse explorer (T3) | `http://localhost:30089` |
|
|
| Grafana (dashboards `swarm-fleet`, `swarm-platform`) | `http://localhost:30300` |
|
|
| Prometheus | `http://localhost:30990` |
|
|
| MinIO console | `http://localhost:30901` |
|
|
| Prototype dev server (`npm run dev`) | `http://localhost:5173` |
|
|
|
|
Rebuild the simulator image and roll it out:
|
|
|
|
```bash
|
|
cd simulator && docker build -t swarm-house/simulator:dev .
|
|
k3d image import swarm-house/simulator:dev -c swarm-sim
|
|
kubectl rollout restart -n swarm statefulset/drone deployment/explorer deployment/exporter
|
|
cd infra/terraform/sim-env && terraform apply
|
|
```
|
|
|
|
**CPU budget knobs** (see [ADR-0009](docs/adr/ADR-0009-bounded-lake-scans.md)):
|
|
`METRIC_FLIGHT_WINDOW` (scan only recent flights), `SCAN_INTERVAL_S`,
|
|
`VIEW_REFRESH_S`, `TREE_CACHE_S`, `KEEP_ALIVE=1` (drones idle after seal instead
|
|
of restarting), `IMU_HZ`. Never scan the full lake on a hot path — it grows with
|
|
pod churn. Long-horizon analysis is a T3 warehouse query, not an exporter job.
|
|
|
|
Runtime data lives under `var/t1` / `var/t3`, owned by uid **10001**
|
|
([ADR-0007](docs/adr/ADR-0007-non-root-image.md),
|
|
[ADR-0008](docs/adr/ADR-0008-runtime-data-paths.md)); both are gitignored.
|
|
Terraform state is local and never committed.
|