Design Notes
This folder collects a curated set of design documents written during Nodaro’s development — the kind of “why it works this way” notes that usually live in an engineer’s head or a private wiki. We publish them because the reasoning behind a system is often more useful than the code alone: the constraints, the alternatives considered, the edge cases, and the invariants that keep things correct.
They read like lightweight RFDs (cf. Oxide’s RFDs, Rust RFCs). Each captures a real feature at the moment it was designed.
Read them as design intent, not as current API reference. These are point-in-time documents — a few predate refactors, and some file paths or field names have since moved. The code and the public docs/ are the source of truth for how the system behaves today. Where a doc and the code disagree, the code wins.
Workflow engine & execution
| Doc |
What it covers |
| array-input-fan-out |
Fan-out semantics (each/all/last/item:N), zip-by-index, cancellation, partial-failure refunds |
| external-call-reconciliation |
Recovering jobs stuck at an external provider — idempotent compare-and-set finalize, per-provider staleness thresholds, stall-retry idempotency |
| smart-progress-bars |
EMA-based progress estimation, outlier guards, a non-linear progress curve, weighted multi-node aggregation |
| router-node |
Conditional control-flow routing between branches of a workflow |
| sub-workflow-node |
Nested workflows as a reusable structural primitive |
| reduce-fan-in |
Fan-in / reduce across fanned-out branches (shipped as the reduce node) |
| generate-script-multi-handle |
Multi-handle output nodes, output dedup, backward compatibility |
| sync-node-job-persistence |
Job persistence wiring and race-condition safety |
Nodes & canvas UX
Prompting
| Doc |
What it covers |
| prompt-wizard |
A wizard that structures prompt output, not content; reference-role weaving |
| prompt-snippets |
Reusable inline prompt fragments — data model, API, pill display layer |
Characters, entities & references
Marketplace & sharing
| Doc |
What it covers |
| component-marketplace |
Reusable workflow components — queued sub-execution, cycle detection, depth limits, snapshot immutability |
| component-marketplace-preview |
The marketplace preview modal — UX, accessibility, interaction edge cases |
| community-sharing |
Sharing entities across the community — data model, RLS, route projection discipline |
AI orchestration & skills
| Doc |
What it covers |
| film-director-skill |
A conversational “film director” skill that assembles an editable workflow on the canvas in real time |
| skill-architecture |
Auto-generating node skill docs from types (ts-morph) with a CI drift gate |
Video authoring & branding
| Doc |
What it covers |
| brand-typography-ramp |
Per-role (heading/body) weight, casing, and tracking on top of brand font family — precedence, the Arabic tracking edge, the loaded-weight constraint |
| brand-image-logo |
Brand logo.image — the URL-only CDN allowlist as the SSRF boundary shared across every render entry point, the contained-in-one-blueprint altitude, the deterministic-net guarantee the lockup scene appears, the onError→wordmark fallback, and the accepted no-dimension-cap risk |