Architecture Decision Records
This directory contains all Architecture Decision Records (ADRs) for floe.
ADR Numbering Policy
Section titled “ADR Numbering Policy”ADR numbers are immutable once assigned. Gaps in numbering occur when:
- ADRs are rejected or withdrawn
- ADRs are superseded and merged into others
- Numbers are reserved for future use
Missing Numbers:
- 0002, 0003, 0004: Historical gaps (pre-documentation system)
- 0013: Merged into ADR-0012 (Data Classification)
ADR Index
Section titled “ADR Index”| ADR | Title | Status |
|---|---|---|
| 0001 | Use Cube for Semantic/Consumption Layer | Accepted |
| 0005 | Apache Iceberg as Enforced Table Format | Accepted |
| 0006 | Use OpenTelemetry for Observability | Accepted |
| 0007 | Include OpenLineage from Start | Accepted |
| 0008 | Standalone Repository Architecture | Accepted |
| 0009 | dbt Owns SQL Transformation | Accepted |
| 0010 | Target-Agnostic Compute | Accepted |
| 0011 | Pluggable Orchestration via OrchestratorPlugin | Accepted |
| 0012 | Data Classification and Governance | Accepted |
| 0014 | Flink for Streaming Workloads | Deferred |
| 0015 | Policy Enforcement Plugin Interface | Accepted |
| 0016 | Platform Enforcement Architecture | Accepted |
| 0017 | Kubernetes-Based Testing Infrastructure | Accepted |
| 0018 | Opinionation Boundaries | Accepted |
| 0019 | Platform Services Lifecycle | Accepted |
| 0020 | Ingestion Plugins | Accepted |
| 0021 | Data Architecture Patterns | Accepted |
| 0022 | Security & RBAC Model | Accepted |
| 0023 | Secrets Management Architecture | Accepted |
| 0024 | Identity and Access Management | Accepted |
| 0025 | Plugin Error Taxonomy | Accepted |
| 0026 | Data Contract Architecture | Accepted |
| 0027 | ODCS Standard Adoption | Accepted |
| 0028 | Runtime Contract Monitoring | Accepted |
| 0029 | Contract Lifecycle Management | Accepted |
| 0030 | Namespace-Based Identity | Accepted |
| 0031 | Infisical as Default Secrets Management | Accepted |
| 0032 | Semantic Layer Compute Plugin Integration | Accepted |
| 0033 | Target Airflow 3.x | Accepted |
| 0034 | dbt-duckdb Iceberg Catalog Workaround | Accepted |
| 0035 | Observability Plugin Interface | Accepted |
| 0036 | Storage Plugin Interface | Accepted |
| 0037 | Composability as Core Principle | Accepted |
| 0038 | Data Mesh Architecture | Accepted |
| 0039 | Multi-Environment Artifact Promotion | Accepted |
| 0040 | Artifact Immutability and Garbage Collection | Accepted |
| 0041 | Artifact Signing and Verification | Accepted |
| 0042 | Linear + Beads Traceability Integration | Superseded |
| 0043 | dbt Compilation Environment Abstraction | Accepted |
| 0044 | Unified Data Quality Plugin Architecture | Accepted |
| 0045 | Compilation Caching Strategy | Accepted |
| 0046 | Agent Memory Architecture (Cognee) | Proposed |
| 0047 | CLI Architecture (Click Unification) | Accepted |
Categories
Section titled “Categories”Foundation
Section titled “Foundation”- 0005 - Apache Iceberg as enforced table format
- 0008 - Repository structure and plugin architecture
- 0016 - Four-layer architecture and platform enforcement
- 0017 - Testing infrastructure
- 0018 - Enforced vs pluggable boundaries
- 0037 - Composability as core architectural principle
Data Pipeline
Section titled “Data Pipeline”- 0009 - dbt as transformation engine
- 0010 - Compute target flexibility
- 0020 - dlt/Airbyte ingestion
- 0021 - Medallion, Data Mesh patterns
- 0034 - dbt-duckdb Iceberg catalog workaround (CRITICAL)
- 0038 - Data Mesh with unified Manifest schema
- 0043 - dbt compilation environment abstraction (local/fusion/cloud)
- 0045 - Content-addressable caching for compilation stages
Observability & Governance
Section titled “Observability & Governance”- 0006 - OpenTelemetry integration
- 0007 - OpenLineage lineage tracking
- 0012 - Data classification
- 0015 - Policy enforcement plugin interface (compile-time code quality)
- 0044 - Unified data quality plugin (Great Expectations, Soda, custom)
Platform Services
Section titled “Platform Services”- 0001 - Cube semantic layer
- 0011 - Pluggable orchestration via OrchestratorPlugin (Dagster, Airflow, Prefect)
- 0019 - Service lifecycle management
- 0032 - Cube delegates to compute plugin (DuckDB-first)
- 0033 - Target Airflow 3.x orchestration
- 0035 - Pluggable observability backends (Jaeger, Datadog, Grafana Cloud)
- 0036 - Pluggable storage backends (S3, GCS, Azure, MinIO)
Security
Section titled “Security”- 0022 - RBAC, network policies, pod security
- 0023 - Secrets management architecture (superseded by 0031)
- 0024 - Identity providers (Keycloak, Dex, Okta)
- 0031 - Infisical as default OSS secrets (supersedes 0023)
Data Contracts
Section titled “Data Contracts”- 0026 - Data contract architecture and enforcement
- 0027 - ODCS v3 standard adoption
- 0028 - Runtime contract monitoring
- 0029 - Contract versioning and lifecycle
- 0030 - Namespace-based product and contract identity
Artifact Distribution
Section titled “Artifact Distribution”- 0039 - Multi-environment promotion with GitOps workflows (dev → staging → prod)
- 0040 - Artifact immutability and garbage collection (Harbor, ECR, ACR, GAR)
- 0041 - Artifact signing and verification (Cosign, keyless + key-based signing)
Deferred
Section titled “Deferred”- 0014 - Streaming workloads (V2.0)
Contributor Tooling
Section titled “Contributor Tooling”- 0042 - Linear + Beads for requirements traceability
- 0046 - Cognee integration for AI agent persistent memory
- 0047 - Unified CLI architecture (Click, floe-core)