Architecture Decisions
Load-bearing decisions grouped into eight fields. Each ADR captures context, the decision taken, alternatives considered, and rationale — the why behind the code.
_legacy/ in v1. Use this index when you need to know why something is the way it is, not what it is — for the "what", see glossary or architecture.
Fields
canvas
Decisions about the editor surface: how graphs are laid out, composed, nested, and stored. Covers the transition from a fixed two-layer canvas to a flat ComfyUI-style workspace, the unified editor tha…
components
Decisions about how node authors extend the platform: the universal base class, the auto-discovery contract, the Python-driven UI system (no .tsx per node), the nodeset rename, the layout-component …
dataflow
Decisions about what flows between nodes, where persistent data lives, and how boundary nodes (PortIn/Out, IterIn/Out, Initialize) shape the graph topology. Wire types and state containers are kept di…
eval
Decisions about batch evaluation: how eval reuses the canvas execution engine (graph-driven, not bespoke pipelines), worker-pool concurrency for env-side throughput, and the batched-inference tier for…
executor
Decisions about the scheduling algorithm: when a node fires, what counts as a seed, how iteration cycles are expressed at runtime, and where graph validity is enforced. Distinct from [dataflow](../dat…
observability
Decisions about what the framework reveals at runtime: execution_id routing so concurrent runs don't cross streams, shell hooks for external interception, the two-layer execution log system (automat…
platform
Decisions that shape the platform as a whole rather than any one subsystem: the framework's zero-domain-knowledge principle, the single-endpoint run API, layered LLM config resolution, the Python-env …
server
Decisions about running nodesets in isolated subprocesses: auto-generating HTTP servers from PortDefs, mounting control-plane routes alongside tool-call routes, and bridging controllers transparentl…
All ADRs by field
| Field | Count | Most recent |
|---|---|---|
canvas | 3 | adr-canvas-003 · 2026-03-31 |
components | 10 | adr-components-010 · 2026-07-04 |
dataflow | 9 | adr-dataflow-009 · 2026-06-11 |
eval | 4 | adr-eval-004 · 2026-05-15 |
executor | 4 | adr-executor-004 · 2026-05-25 |
observability | 5 | adr-observability-005 · 2026-05-10 |
platform | 8 | adr-platform-008 · 2026-06-11 |
server | 4 | adr-server-004 · 2026-06-15 |