Architecture Decision Records (ADR)¶
This directory contains the Architecture Decision Records for the AKKO platform. Each ADR follows the MADR format and captures a significant technical or architectural choice along with its context, alternatives and consequences.
How to read an ADR¶
Every ADR has the same skeleton:
- Status — Proposed / Accepted / Deprecated / Superseded
- Context — the forces that made the decision necessary
- Considered options — alternatives evaluated
- Decision — the option retained
- Rationale — why this option won
- Consequences — positive, negative, neutral
- Implementation — concrete file paths in this repo
- Validation — how we know the decision still holds
- References — commits, PRs, external links
Index¶
| # | Title | Status | Date |
|---|---|---|---|
| 001 | Iceberg over Delta / Hudi | Accepted | 2025 |
| 002 | Airflow over Dagster | Accepted | 2025 |
| 003 | Polaris over Hive Metastore | Accepted | 2025 |
| 004 | Redpanda over Kafka | Accepted | 2025 |
| 006 | Ad-hoc to Production Workflow | Accepted | 2025 |
| 007 | AI Search JVM-local Cache | Accepted | 2026-04-24 |
| 020 | Monitoring Stack Relicensing | Accepted | 2026-04 |
| 021 | Catalog Manager Pro | Accepted | 2026-04 |
| 022 | CI Strategy | Accepted | 2026-04 |
| 027 | Storage Backend — SeaweedFS as Default, BYOS for External | Accepted | 2026-04-25 |
| 028 | Observability Backend — VictoriaLogs + Perses + Fluent Bit | Accepted | 2026-04-25 |
| 029 | Governance over License — Tool Selection Rule | Accepted | 2026-04-25 |
| 034 | Helm chart distribution — OCI artifact in Harbor | Accepted | 2026-04-25 |
Numbering convention¶
- 001-019 — Foundational decisions (storage format, orchestration, catalog, streaming)
- 020-029 — Sprint 41-43 platform redesigns (relicensing wave response)
- 030-039 — Sprint 44-46 distribution / commercial-readiness decisions
- 040+ — Reserved for future sprints
Adding a new ADR¶
- Pick the next free number.
- Copy the MADR skeleton from any existing ADR (eg.
adr-029-governance-over-license.md). - Add a row to the index table above in the same commit.
- Reference the ADR from
MEMORY.mdif it introduces a new project rule. - CI (
.github/workflows/doc-consistency.yml) will fail if the index is out of sync.
Related¶
- Cross-cutting rule: every load-bearing brick must satisfy the 5-criterion grid defined in ADR-029.
- Strategic roadmap:
/Users/ab2dridi/newera/akko-technical-map/roadmap/current.md - Sprint history:
/Users/ab2dridi/newera/akko-technical-map/sprints/