Sylvain Tremblay
aba36b1b69
Remove three never-used surfaces flagged in branch self-review: - PromptSource::writer / with_writer (unwired since the crate's first commit; Arc<dyn Write> couldn't even be written to without interior mutability, so the seam never worked as intended) - OidcSession::is_openbao_token_expired (duplicated is_expired, no callers) - HARMONY_SECRETS_URL env var (defined, never read) Log before swallowing real StoreSource::get errors so a down or misconfigured OpenBao is no longer indistinguishable from "key absent". Docs: ADR 020-1 now documents the actual OPENBAO_URL/VAULT_ADDR var (the agnostic HARMONY_SECRETS_URL it proposed was never built) with the adapter-layer-vs-domain rationale; rename stale ConfigManager references to ConfigClient in ROADMAP/01 and a firewall_pair comment. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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 |
| 022 | Fleet Agent Upgrade Procedure | Accepted |
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