Jean-Gabriel Gill-Couture
064fa1da0d
Two design documents framing the next push. `ROADMAP/fleet_platform/v0_2_plan.md` — three-day production push. Replaces the open-ended chapter structure of v0_1_plan.md for the period between the walking-skeleton merge and v0.1.0 in production. Focus is locking the fleet module's public API surface so the inevitable physical refactor (out of `harmony/modules/fleet/`, into `fleet/harmony-fleet/`) is mechanical when we get to it. Anchored in the principle from JG's *Pour l'amour des compilateurs* talk: design the brick before moving the brick. `docs/adr/022-fleet-agent-upgrade.md` — agent upgrade procedure. K8s rolling-update shape applied to one host: drain in-flight work, stage versioned binary alongside old, smoke-test, atomic symlink swap, both agents alive briefly, operator verifies new agent's heartbeat then sends explicit stop signal to old, old exits cleanly. No version is ever erased — N-history on disk is the rollback target. Operator-driven cutover (not self-stopping) so the most-trusted side decides the handoff. Implementation deferred to post-v0.1 backlog; spec exists so anyone can build it without reinventing the design. ADR README index updated.
65 lines
3.6 KiB
Markdown
65 lines
3.6 KiB
Markdown
# 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](./000-ADR-Template.md) | ADR Template | Reference |
|
|
| [001](./001-rust.md) | Why Rust | Accepted |
|
|
| [002](./002-hexagonal-architecture.md) | Hexagonal Architecture | Accepted |
|
|
| [003](./003-infrastructure-abstractions.md) | Infrastructure Abstractions | Accepted |
|
|
| [004](./004-ipxe.md) | iPXE | Accepted |
|
|
| [005](./005-interactive-project.md) | Interactive Project | Proposed |
|
|
| [006](./006-secret-management.md) | Secret Management | Accepted |
|
|
| [007](./007-default-runtime.md) | Default Runtime | Accepted |
|
|
| [008](./008-score-display-formatting.md) | Score Display Formatting | Proposed |
|
|
| [009](./009-helm-and-kustomize-handling.md) | Helm and Kustomize Handling | Accepted |
|
|
| [010](./010-monitoring-and-alerting.md) | Monitoring and Alerting | Accepted |
|
|
| [011](./011-multi-tenant-cluster.md) | Multi-Tenant Cluster | Accepted |
|
|
| [012](./012-project-delivery-automation.md) | Project Delivery Automation | Proposed |
|
|
| [013](./013-monitoring-notifications.md) | Monitoring Notifications | Accepted |
|
|
| [015](./015-higher-order-topologies.md) | Higher Order Topologies | Proposed |
|
|
| [016](./016-Harmony-Agent-And-Global-Mesh-For-Decentralized-Workload-Management.md) | Harmony Agent and Global Mesh | Proposed |
|
|
| [017-1](./017-1-Nats-Clusters-Interconnection-Topology.md) | NATS Clusters Interconnection Topology | Proposed |
|
|
| [018](./018-Template-Hydration-For-Workload-Deployment.md) | Template Hydration for Workload Deployment | Proposed |
|
|
| [019](./019-Network-bond-setup.md) | Network Bond Setup | Proposed |
|
|
| [020-1](./020-1-zitadel-openbao-secure-config-store.md) | Zitadel + OpenBao Secure Config Store | Accepted |
|
|
| [020](./020-interactive-configuration-crate.md) | Interactive Configuration Crate | Proposed |
|
|
| [022](./022-fleet-agent-upgrade.md) | Fleet Agent Upgrade Procedure | Accepted |
|
|
|
|
## Contributing
|
|
|
|
When making a significant technical change:
|
|
|
|
1. **Check existing ADRs** — the decision may already be documented
|
|
2. **Create a new ADR** using the [template](./000-ADR-Template.md) if the change warrants architectural discussion
|
|
3. **Set status to Proposed** and open it for team review
|
|
4. Once accepted and implemented, update the status accordingly
|