Skip to content

ADR Index

Architectural Decision Records for OceanCanvas. Each ADR is a single decision, locked, with rationale.

The reference document for this folder is OC_TA.md — Technical Architecture. Every ADR locks a piece of TA. ADRs and TA live together because they are both settled — TA captures what is true now, ADRs capture how it became true.

For exploration of open technical questions that haven't yet closed into ADRs, see ../rfc/.

What gets an ADR

A single architectural decision, locked. ADRs commit. They are short. They are written after a decision is made, not as part of making it. ADRs are append-only — superseded by new ADRs, never edited in place.

If the decision needs deliberation first, write an RFC. If the work is "set up the thing", neither — it's a config file and a commit.

Reference

Doc Purpose
OC_TA.md Components, contracts, constraints, stack, RFC/ADR state map. The reference doc this folder anchors to.
ADR_TEMPLATE.md ADR template. Read the "Notes on writing ADRs" section before starting.

ADRs

ADR Title Status TA anchor
ADR-001 Prefect as orchestration Accepted components/pipeline · stack
ADR-002 dlt for REST/JSON ingestion Accepted components/pipeline · stack
ADR-003 xarray + requests for NetCDF sources Accepted components/pipeline · stack
ADR-004 Three-layer data store Accepted components/data-store
ADR-005 No database in v1 Accepted constraints
ADR-006 p5.js as sketch language Accepted components/render-system · stack
ADR-007 Puppeteer for server-side rendering Accepted components/render-system · stack
ADR-008 Shared payload format for preview and pipeline Accepted contracts/render-payload · constraints
ADR-009 deck.gl + MapLibre for spatial rendering Accepted components/web-frontend · stack
ADR-010 Observable Plot for time series Accepted components/web-frontend · stack
ADR-011 Docker Compose deployment Accepted components/service-layer · stack
ADR-012 Caddy as static file server Accepted components/service-layer · stack
ADR-013 GitHub Actions for code CI only Accepted components/ci · stack
ADR-014 Synthetic-data e2e test as CI gate Accepted components/ci
ADR-015 Processed JSON format with multi-band handling Accepted contracts/processed-data
ADR-016 Single-author recipes in Phase 1 Accepted components/data-store · constraints
ADR-017 One editorial layout per source Accepted components/web-frontend
ADR-018 Recipe YAML schema (flat + comment-marker) Accepted contracts/recipe-yaml
ADR-019 Render payload JSON schema Accepted contracts/render-payload
ADR-020 Live preview architecture Accepted components/render-system · components/web-frontend
ADR-021 YAML round-tripping Accepted contracts/recipe-yaml · components/web-frontend
ADR-022 CLI entry point, invocation model, dependencies Accepted components/pipeline · stack
ADR-023 Pipeline parallelisation and render concurrency Accepted components/pipeline · components/render-system
ADR-024 Key moment detection algorithm Accepted components/render-system
ADR-025 Recipe lifecycle on source unavailability Accepted components/pipeline · constraints
ADR-026 Audio stem system Superseded by ADR-027 components/render-system
ADR-027 Generative audio composition Accepted components/render-system · contracts/recipe-yaml
ADR-028 Tension arc as shared primitive Accepted components/render-system · contracts/recipe-yaml · contracts/render-payload
ADR-029 Compose sidecars for recipe save and video export Accepted components/service-layer · components/web-frontend · stack

State map

The live state of all RFCs and ADRs lives in OC_TA.md (Map). This index mirrors the ADR portion. RFCs in deliberation are tracked in ../rfc/index.md.

When an RFC closes into a new ADR, three things update together:

  1. The new ADR file is added here.
  2. The RFC's status flips to Decided in ../rfc/index.md and in OC_TA.md (Map).
  3. The new ADR is added to the ADRs table in OC_TA.md (Map). If it locks a piece of the stack, the Stack table in OC_TA.md also updates with the ADR pointer.