Matrioshka & registries

Matrioshka workflows

A Matrioshka workflow is a workflow that contains other workflows. The name comes from the Russian nesting dolls. Open the outer one, find another inside, open that one, find another. Flowzart’s canvas works the same way. A node on the outer canvas can be a fully-formed workflow in its own right, with its own nodes, its own logic, and its own outputs.

Each level of the nesting is independent. The outer workflow doesn’t care how the inner one is built; it only cares about what goes in and what comes out. And every level stays inspectable: opening a Matrioshka node reveals its inner canvas exactly as if it were the top level. Nothing is hidden. Nothing is opaque.

This matters for two reasons:

• Composition without complexity. A workflow that’s a hundred nodes flat is unmaintainable. The same workflow grouped into nested pieces (one for fetching, one for transforming, one for delivering) fits in your head. Each piece is a unit you can reason about in isolation.
• Reuse without duplication. A nested workflow can be saved as a node and dropped into other workflows, treated as a single composable unit instead of copy-pasted nodes scattered across files. (Whether edits to the inner workflow propagate to every place it’s used is an open question; see “Working with Matrioshka” below.)

Registries

A registry is a place where Flowzart users publish nodes for other users to install. Some nodes are built-in, shipped by Flowzart. Others are created by the community: someone builds a useful Matrioshka workflow, saves it as a node, and publishes it to a registry. Anyone with access to that registry can pull it into their own canvas and start using it.

Three things follow from that:

• Custom nodes are first-class. A node a user built and a node Flowzart shipped behave the same way on the canvas. There is no second tier.
• Distribution is opt-in. Publishing a node is a deliberate action. Nodes stay local until their author sends them somewhere.
• Registries can be shared or private. A team can run a registry scoped to itself. The community can run public ones. The same node can live in both, at different versions.

Sharing fixes upstream

What this combination unlocks is unusual. When a user installs a community node and finds a bug in it, they can open it up, fix it on their own canvas, and propose the fix back to the registry where they got it. The maintainer reviews the change. If it’s good, it gets merged. From that moment on, every user of that node receives the fix on their next update.

This isn’t a workaround layered on top; it’s how the system is built. Custom nodes are workflows, workflows are inspectable, and registries have a contribution path. Bugs in shared building blocks don’t sit there forever waiting for the original author to notice. Anyone can pick them up.

Working with Matrioshka

From workflow to node: the Matrioshka Contract. A Matrioshka workflow becomes a node by declaring a Matrioshka Contract — a specification of the workflow’s public interface (its inputs and its outputs) that the rest of the canvas treats as the node’s surface. Once a Contract is declared, the ImEx (Import/Export) system handles the rest: the workflow can be exported as a Matrioshka node, imported into other workflows, and composed alongside any built-in node.

A single workflow can declare more than one Matrioshka Contract. Each Contract exports as a separate Matrioshka node. So one well-designed workflow can produce a family of related custom nodes — different surface APIs over a shared internal graph. Useful when several nodes share most of their logic but differ in which inputs and outputs they expose.

Reuse without redeclaration. Inside the workflow that backs a Matrioshka Contract, you compose with the same node palette as any other workflow — including nodes you’ve already defined elsewhere or imported via ImEx. You don’t redeclare them; you reference them. A Matrioshka node you build can use other Matrioshka nodes you’ve already built, building higher-order capabilities from lower-order ones without duplicating logic. This is what makes Matrioshka registries multiplicative rather than additive: every node in a registry can compose with every other node, and the resulting graph stays as inspectable as the original.

Opening a Matrioshka node. Double-click any Matrioshka node on the canvas to descend into its inner workflow. The viewport replaces the current view with the inner one; a breadcrumb at the top shows the path back out, and Esc returns one level up. The same gesture works at every nesting level — there’s no maximum depth.

Working with registries

Publishing a node. Right-click any node you own on the canvas and pick “Publish to registry…” — a modal asks which registry to push to and which version label to attach. The node lands in the registry as soon as the push completes, and anyone with read access to that registry can install it from that point on.

Discovering nodes. A registry’s index page lists every published node with its category, author, and current version. Search filters by name, tag, or author; categories are browsable as a tree. A “recent” view surfaces nodes published or updated in the last week — useful for spotting new building blocks the community has shared.

Contributing a fix. Install the node like any other. When you find something to change, open it on your canvas — the local copy is yours to edit freely. When the fix is ready, “Propose changes” sends a pull request back to the source registry with a diff of your edits. The maintainer reviews; if it merges, every user of that node receives the update on their next sync. This is the same flow as the “Sharing fixes upstream” section above; it’s the one path, surfaced through the canvas.

Public vs private registries. Anyone can create a registry from their account settings. Public registries are searchable and installable by anyone — that’s how the community library lives. Private registries require an explicit member invite; access is managed via a member list with read, write, and admin roles. A team typically runs one private registry for its internal nodes and pulls from public ones for shared building blocks.

Versioning. Registry nodes follow SemVer (major.minor.patch). Patch and minor updates apply automatically on your next sync — bug fixes and backward-compatible additions land without intervention. Major-version updates require a deliberate accept; an “update available” prompt surfaces the new version with a changelog summary so you can decide whether to take the breaking change. You can also pin any node to a specific version per workflow if you need to lock the dependency.