RFC Index
Requests for Comments — open technical questions for OceanCanvas. Each RFC explores a single question with alternatives and trade-offs, then closes into one or more ADRs.
The reference document for the technical plane is OC_TA.md, which lives with the ADRs (the settled tier). RFCs anchor to the Components, Contracts, and Constraints sections of OC_TA.md. Once an RFC closes, it produces ADRs that update OC_TA.md.
For settled architectural decisions, see ../adr/.
What gets an RFC
An open technical question with plausible alternatives and trade-offs that require deliberation. RFCs explore. They do not specify implementation. They close into one or more ADRs once a decision is made.
If the answer is mostly known going in, skip the RFC and write an ADR. If the work is "set up the thing", neither — it's a config file and a commit. The "Why this is an RFC" sentence in the RFC header is the test: if it's hard to write, the file should not be an RFC.
Reference
| Doc | Purpose |
|---|---|
| OC_TA.md | Components, contracts, constraints, stack, RFC/ADR state map. Lives with ADRs (the settled tier). RFCs anchor to its sections. |
| RFC_TEMPLATE.md | RFC template. Read the "Notes on writing RFCs" section before starting. |
RFCs
| RFC | Title | Status | Closes into | TA anchor |
|---|---|---|---|---|
| RFC-001 | Recipe YAML schema | Decided | ADR-018 | contracts/recipe-yaml |
| RFC-002 | Render payload format | Decided | ADR-008 + ADR-019 | contracts/render-payload |
| RFC-003 | Recipe lifecycle on source unavailability | Decided | ADR-025 | components/pipeline · constraints |
| RFC-004 | Live preview architecture | Decided | ADR-020 | components/render-system · components/web-frontend |
| RFC-005 | YAML round-tripping | Decided | ADR-021 | contracts/recipe-yaml |
| RFC-006 | Audio system design | Decided | ADR-026 | components/render-system |
| RFC-007 | Key moment detection | Decided | ADR-024 | components/render-system |
| RFC-008 | Pipeline parallelisation strategy | Decided | ADR-023 | components/pipeline |
| RFC-009 | Pipeline CLI interface | Decided | ADR-022 | components/pipeline |
| RFC-010 | Generative audio composition | Decided | ADR-027 (supersedes ADR-026) | components/render-system |
| RFC-011 | Tension arc as shared primitive | Decided | ADR-028 | components/render-system · contracts/recipe-yaml · contracts/render-payload |
State map
The live state of all RFCs and ADRs lives in OC_TA.md (Map). This index mirrors the RFC portion. ADRs (settled decisions) are tracked in ../adr/index.md.
When an RFC closes:
- Its status here flips from Draft v0.1 (or whatever revision) to Decided.
- One or more ADR files appear in
../adr/. - The RFC row in
OC_TA.md(Map) flips to Decided and links to the closing ADR(s); the Stack table picks up new entries if the RFC unlocked stack-level decisions.
A note on numbering
RFCs and ADRs are independently numbered. The canonical list is RFC-001 through RFC-011 in the table above. An earlier draft used a different 7-RFC numbering — three topics were demoted to ADRs once the deliberation turned out to be smaller than expected:
- Processed JSON format (was RFC-003) → ADR-015.
- Docker Compose stack (was RFC-004) → ADR-011 + the
compose/docker-compose.ymlconfig file itself. - GitHub Actions CI (was RFC-007) → ADR-013 + ADR-014.
The current list adds three RFCs surfaced from PRD open threads: Recipe lifecycle (RFC-003), Live preview architecture (RFC-004), YAML round-tripping (RFC-005).