Jean-Gabriel Gill-Couture
2ad1911fac
All checks were successful
Run Check Script / check (pull_request) Successful in 1m53s
72 lines
4.2 KiB
Markdown
72 lines
4.2 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 |
|
|
| [023](./023-deploy-architecture.md) | Deploy Architecture | Accepted |
|
|
| [024](./024-fleet-platform-capability-decomposition.md) | Fleet Platform Capability Decomposition | Accepted |
|
|
| [025](./025-fleet-device-secret-access.md) | Fleet Device Secret Access | Accepted |
|
|
| [025-3](./025-device-secret-access/025-3-groups-as-security-boundary.md) | Groups as the Security Boundary — Scale & Security Analysis | Accepted |
|
|
| [026](./026-application-lifecycle-cli.md) | Application Lifecycle CLI | Accepted |
|
|
| [027](./027-multi-tenant-identity.md) | Multi-Tenant Cloud Identity | Accepted |
|
|
| [028](./028-typed-score-references.md) | Typed Score References | 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](./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
|