Jean-Gabriel Gill-Couture
51b39505bb
Some checks failed
Run Check Script / check (pull_request) Failing after 37s
Re-frame ADR-021 from an accepted shell-executor decision into an explicit problem statement plus one candidate proposal (Alternative A), with an Open Questions section capturing the concerns raised during review: wrong abstraction level, no idempotency, no resource model, no typed status, incoherence with the Score-Topology-Interpret pattern, and weak security posture. Add ADR-022 enumerating four alternatives: - A: shell command executor (current scaffold) - B: mini-kubelet with typed resource manifests and reconcilers - C: embedded Score interpreter on the agent - D: hybrid — typed manifests now, Scores later Recommends Alternative D: ship typed AgentManifest/AgentStatus with a small fixed reconciler set for the IoT MVP, keeping an explicit migration seam to the Score-based end state once Scores become uniformly wire-serializable. Also documents what specifically is wrong with the happy-path shell executor in harmony_agent/src/desired_state.rs and clarifies that the NATS KV watch + typed CAS write skeleton is reusable, while the execute_command shell-out should be gated behind an audited ShellJob variant or deleted once real reconcilers land.
Architecture Decision Records
An Architecture Decision Record (ADR) documents a significant architectural decision made during the development of Harmony — along with its context, rationale, and consequences.
Why We Use ADRs
As a platform engineering framework used by a team, Harmony accumulates technical decisions over time. ADRs help us:
- Track rationale — understand why a decision was made, not just what was decided
- ** onboard new contributors** — the "why" is preserved even when team membership changes
- Avoid repeating past mistakes — previous decisions and their context are searchable
- Manage technical debt — ADRs make it easier to revisit and revise past choices
An ADR captures a decision at a point in time. It is not a specification — it is a record of reasoning.
ADR Format
Every ADR follows this structure:
| Section | Purpose |
|---|---|
| Status | Proposed / Pending / Accepted / Implemented / Deprecated |
| Context | The problem or background — the "why" behind this decision |
| Decision | The chosen solution or direction |
| Rationale | Reasoning behind the decision |
| Consequences | Both positive and negative outcomes |
| Alternatives considered | Other options that were evaluated |
| Additional Notes | Supplementary context, links, or open questions |
ADR Index
| Number | Title | Status |
|---|---|---|
| 000 | ADR Template | Reference |
| 001 | Why Rust | Accepted |
| 002 | Hexagonal Architecture | Accepted |
| 003 | Infrastructure Abstractions | Accepted |
| 004 | iPXE | Accepted |
| 005 | Interactive Project | Proposed |
| 006 | Secret Management | Accepted |
| 007 | Default Runtime | Accepted |
| 008 | Score Display Formatting | Proposed |
| 009 | Helm and Kustomize Handling | Accepted |
| 010 | Monitoring and Alerting | Accepted |
| 011 | Multi-Tenant Cluster | Accepted |
| 012 | Project Delivery Automation | Proposed |
| 013 | Monitoring Notifications | Accepted |
| 015 | Higher Order Topologies | Proposed |
| 016 | Harmony Agent and Global Mesh | Proposed |
| 017-1 | NATS Clusters Interconnection Topology | Proposed |
| 018 | Template Hydration for Workload Deployment | Proposed |
| 019 | Network Bond Setup | Proposed |
| 020-1 | Zitadel + OpenBao Secure Config Store | Accepted |
| 020 | Interactive Configuration Crate | Proposed |
Contributing
When making a significant technical change:
- Check existing ADRs — the decision may already be documented
- Create a new ADR using the template if the change warrants architectural discussion
- Set status to Proposed and open it for team review
- Once accepted and implemented, update the status accordingly