harmony/docs/adr/README.md

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:

1. Check existing ADRs — the decision may already be documented
2. Create a new ADR using the template 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