Skip to content

README.md

Latest commit

 

History

History
95 lines (67 loc) · 3.5 KB

README.md

File metadata and controls

95 lines (67 loc) · 3.5 KB
Status Active
Owner HyperFleet Architecture Team
Last Updated 2026-05-11

Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records (ADRs) for HyperFleet. Each ADR captures a significant decision, why it was made, and what was rejected.

When to Write an ADR

Write an ADR when a decision:

  • Affects multiple components or teams
  • Is hard to reverse
  • Has meaningful trade-offs between alternatives
  • Would leave future contributors wondering "why did they do it this way?"

Do not write an ADR for implementation details, config changes, or decisions that are obvious from the code.

Naming Convention

NNNN-short-title.md

Examples: 0001-use-cloudevents-for-adapter-pulses.md, 0002-sentinel-pull-model.md

Numbers are sequential. Use the next available number.

Template

Copy this into your new ADR file:

---
Status: Proposed | Active | Deprecated
Owner: <team>
Last Updated: YYYY-MM-DD
---

# NNNN — Title of Decision

## Context

What is the problem or situation forcing this decision?
One short paragraph.

## Decision

What did we decide? State it plainly.

## Consequences

**Gains:** What becomes easier or better.
**Trade-offs:** What becomes harder or worse.

## Alternatives Considered

| Alternative | Why Rejected |
|-------------|--------------|
| Option A    | Reason       |
| Option B    | Reason       |

ADR Index

ADR Title Status Date
0001 CloudEvents as the Inter-Component Event Format Active 2026-04-15
0002 Pluggable Message Broker via hyperfleet-broker Library Active 2026-04-15
0003 OpenAPI 3.0 as the System Contract (API-First Development) Active 2026-04-15
0004 Sentinel as a Stateless Polling Reconciliation Loop Active 2026-04-15
0005 Config-Driven Adapter Framework (Single Binary, Multiple Deployments) Active 2026-04-15
0006 CEL as the Shared Expression Evaluation Engine Active 2026-04-15
0007 Kubernetes-Style Conditions-Based Status Model Active 2026-04-15
0008 Dynamic Status Aggregation (Compute on Write) Active 2026-04-16
0009 UUID v7 for Cluster and NodePool Identifiers Active 2026-04-15
0010 JSONB for Provider-Agnostic Cluster and NodePool Spec Storage Active 2026-04-15
0011 Testcontainers for Integration Tests Active 2026-04-16
0012 Hard-Delete Ownership and Execution Proposed 2026-04-23
0013 Force Delete Scope: Database-Only Proposed 2026-05-01
0014 Konflux for Container Image Build and Release Active 2026-04-21
0015 Eventual Consistency for the API Read Path Active 2026-05-08
0016 Helm OCI Distribution via Konflux Active 2026-05-11
0017 Selective Message Acknowledgment in Adapters Active 2026-05-25