Architecture decision records
The ADRs in this directory are the current architectural truth for Baleia. CR documents remain the change history; when an ADR and a CR disagree, the ADR wins.
Format: MADR, one decision per file, numbered in order. Start from
template.md.
Index
| ADR | Title | Status |
|---|---|---|
| 0001 | Baleia is a control plane, never a data plane | Accepted |
| 0002 | Connections, engines, catalogs and bindings | Accepted |
| 0003 | How a catalog reaches Trino (the Trino binder) | Accepted |
| 0004 | Catalog-store plugin distribution | Accepted |
| 0005 | Trino security model | Accepted |
| 0006 | Multi-engine scope | Accepted |
| 0007 | Adapters are constructed only at the wiring sites | Accepted |
| 0008 | Error and secret boundaries | Accepted |
| 0009 | Recurring jobs run on Temporal Schedules | Accepted |
| 0010 | Development environments | Proposed |
| 0011 | Security of direct connections to user-supplied hosts | Accepted |
| 0012 | Semantic layer roadmap (no dbt) | Accepted |
| 0013 | Saved content model | Accepted |
Owner decisions
The owner decisions referenced across the backlog and where each one is recorded:
| Decision | Summary | Recorded in |
|---|---|---|
| D1 (revised) | Baleia is multi-engine: federated engines and direct engines | 0006 |
| D2 | Compose stays as the quickstart; minikube/Helm for dev parity | 0010 (Proposed) |
| D3 | Managed-only authority: adopted catalogs are reported, never mutated | 0003 |
| D4 | Registry secrets: Phase A by default (env/file refs stored as references) | 0003, #31 |
| D5 | Connection test topology: metadata, direct engine and bind:<engine> checks | 0011, #12 |
| D6 | The workspace role matrix lives in #16 | #16 |
| D7 | Refresh token in an HttpOnly cookie; no tokens in URLs | #51, #55 |
| D8 | User SQL runs as a per-user Trino identity | 0005 |
| D9 | Semantic layer: simple metrics in v1, Lightdash-level in v2, no dbt | 0012 |
| D10 | The four-concept model: connections, engines, catalogs, bindings | 0002 |
| D11 | v1 provider scope | 0002 |
Superseding an ADR
Never edit the decision of an accepted ADR in place. To change it:
- Add a new ADR with the next number and a
Supersedes: NNNNline under its status. - Change the old ADR's status to
Superseded by NNNN(the only edit an accepted ADR receives, besides its "Current compliance" section). - Update the index above.
Each ADR has a Current compliance section that says where the code does not follow the decision yet and which issue fixes it. Update that section as those issues land.