eSlider
bed6f93626
CI & Release / Verify documentation (push) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify documentation (pull_request) Successful in 5s
CI & Release / Verify simulator (pull_request) Failing after 9s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
Document caveman-full as the collaboration voice in AGENTS and CONTRIBUTING, and add Gitea issue/PR templates that pre-fill terse structure.
98 lines
4.6 KiB
Markdown
98 lines
4.6 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
|
|
|
|
### Caveman style (default for collaboration)
|
|
|
|
**Issues, pull requests, and code reviews** use **caveman-full** by default:
|
|
|
|
- Short sentences or fragments; drop articles and filler when clear
|
|
- Lead with fact, verdict, or ask — not preamble
|
|
- Bullets over paragraphs; one idea per line
|
|
- Keep technical terms, acronyms, paths, and code exact
|
|
- English only; no identifying references (same as all repo prose)
|
|
|
|
README tiers: root [`README.md`](README.md) = **caveman-lite** (full sentences, less filler);
|
|
component READMEs = **caveman-full**. Design docs in `docs/` stay readable prose unless
|
|
editing for consistency.
|
|
|
|
Templates: [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/),
|
|
[`.github/pull_request_template.md`](.github/pull_request_template.md).
|
|
|
|
- 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.
|