Reaktor DocsArchitectureClaude

Architecture · Claude

Flow Analysis

Comparison of react-flow, compose-flow, and reaktor-flow architecture and tradeoffs.

Use whenUse when working on visual graph editing and flow UI decisions.
SourceClaude
Route/docs/flow-analysis

01 React Flow — The Reference Implementation

Architecture

React Flow is built on a Zustand store at its core. The <ReactFlow> component wraps a <ReactFlowProvider> which initializes this store. All state — nodes, edges, viewport, selection, connection-in-progress — lives in one centralized store. Components subscribe to slices via useStore(selector).

Rendering pipeline: DOM-based nodes (each node is a positioned <div>), SVG-based edges (rendered in an <svg> layer beneath the node layer). Nodes are real DOM elements, enabling rich HTML content, form inputs, and full accessibility.

Data Model

TypeKey FieldsField Count
Node<T> id, position, data, type, measured, parentId, handles, draggable, selectable, connectable, deletable, dragHandle, extent, expandParent, origin, zIndex, resizing, focusable, ariaRole 25+
Edge<T> id, source, target, sourceHandle, targetHandle, type, data, label, animated, markerStart, markerEnd, reconnectable, interactionWidth, selectable, deletable 18+
Handle id, type, position, isConnectable, isConnectableStart, isConnectableEnd, isValidConnection 7+
Connection source, target, sourceHandle, targetHandle 4
Viewport x, y, zoom 3

Built-in Types

Node Types

default · input · output · group

Edge Types

default (bezier) · straight · step · smoothstep · simplebezier

Feature Surface

~100

Props on <ReactFlow>

17+

Hooks exposed

~40

Event callbacks

12

Sub-components

Interaction Features

  • Node dragging with configurable threshold, drag handles, auto-pan
  • Edge connection by drag (handle-to-handle) and click-to-connect mode
  • Edge reconnection (drag existing edge to new target)
  • Multi-selection (shift+click, rubber-band selection box)
  • Selection box drag, keyboard delete
  • Snap-to-grid, node extent constraints (including "parent")
  • Auto-pan on drag near canvas edges
  • Pan via drag, scroll, or space+drag
  • Zoom via scroll, pinch, double-click, or ctrl+scroll
  • Full keyboard navigation (tab through nodes/edges)

Components

  • <ReactFlow>, <ReactFlowProvider>
  • <Handle> with connection validation
  • <Background> (dots, lines, cross)
  • <Controls>, <MiniMap>, <Panel>
  • <ViewportPortal>, <NodeResizer>, <NodeToolbar>
  • <BaseEdge>, <EdgeLabelRenderer>

Hooks

HookPurpose
useReactFlow()Imperative API: get/set/add nodes & edges, fitView, zoom, viewport, screenToFlowPosition, deleteElements, getIntersectingNodes
useNodes() / useEdges()Reactive accessors
useNodesState() / useEdgesState()State + setter + onChange bundles
useViewport()Current viewport
useOnViewportChange()Viewport start/change/end callbacks
useConnection()In-progress connection data
useHandleConnections()Edges connected to a specific handle
useNodeId()Current node context
useNodesData()Subscribe to specific node data
useNodesInitialized()Measurement readiness signal
useOnSelectionChange()Selection events
useStore() / useStoreApi()Direct Zustand access
useKeyPress()Keyboard state
useUpdateNodeInternals()Force re-measure

Event System (~40 callbacks)

CategoryEvents
Nodeclick, doubleClick, dragStart, drag, dragStop, mouseEnter, mouseMove, mouseLeave, contextMenu, delete
Edgeclick, doubleClick, mouseEnter, mouseMove, mouseLeave, contextMenu, reconnect, reconnectStart, reconnectEnd, delete
Connectionconnect, connectStart, connectEnd, clickConnectStart, clickConnectEnd, isValidConnection
Paneclick, contextMenu, scroll, mouseMove, mouseEnter, mouseLeave
Selectionchange, dragStart, drag, dragStop, start, end, contextMenu
Viewportmove, moveStart, moveEnd
Lifecycleinit, error, delete, beforeDelete

02 Compose Flow — Current State

Package: dev.shibasis.composeflow
KMP Targets: commonMain, Android, iOS/macOS (Darwin), JVM Desktop, JS/Web

Rendering Pipeline

Compose graphicsLayer transform for viewport (translate + scale), DOM-positioned nodes via Box + offset, Canvas-drawn edges via DrawScope. This is a good architectural match to react-flow’s DOM-nodes + SVG-edges pattern.

What’s Implemented

Data Model

TypeFieldsFile
Nodeid, position, data, type, width, height, measured, handles, sourcePosition, targetPosition, parentId, showDefaultHandles, selected, dragging, hidden, zIndexmodel/Model.kt
Edgeid, source, target, sourceHandle, targetHandle, type, data, label, selected, hidden, animated, markerEnd, zIndexmodel/Model.kt
Handleid, type, position, offset, insetmodel/Model.kt
Connectionsource, target, sourceHandle, targetHandlemodel/Model.kt
Viewportx, y, zoommodel/Model.kt

Change System

  • NodeChange sealed interface: NodeAddChange, NodeRemoveChange, NodeReplaceChange, NodeSelectionChange, NodePositionChange, NodeDimensionChange
  • EdgeChange sealed interface: EdgeAddChange, EdgeRemoveChange, EdgeReplaceChange, EdgeSelectionChange
  • applyNodeChanges(), applyEdgeChanges(), addEdge() helpers

State Management

  • NodesState — nodes, replaceNodes(), updateNodes(), onNodesChange(), destructuring operators
  • EdgesState — edges, replaceEdges(), updateEdges(), onEdgesChange(), destructuring operators
  • ReactFlowState — viewport, canvasSize, selectedNodeIds/EdgeIds, setViewport(), panBy(), screenToFlowPosition(), centerOn(), focusNode(), zoomTo(), zoomBy(), fitView()
  • ReactFlowProvider, useReactFlowState(), useViewport()

Main Composable — ReactFlow()

~25 parameters: nodes, edges, state, nodeTypes, onNodesChange, onConnect, onNodeClick, fitView, fitViewOptions, showBackground, backgroundVariant, showControls, showMiniMap, minZoom, maxZoom, defaultNodeWidth/Height, nodeRenderStyle, edgeRenderStyle, edgePathStyle, handleRenderStyle, onPaneClick, overlay, viewportOverlay

Components

  • FlowBackground — Dots, Lines, Cross patterns
  • FlowControls — zoom in/out/fit with percentage display
  • MiniMap — overview with node/edge rendering
  • Panel with PanelPosition
  • FlowNodeBox — node container with drag, click, measurement
  • Handle composable — circular handles with source/target styling
  • DefaultNode — label + type display

Interactions

  • Wheel/trackpad zoom with ctrl/meta modifier detection
  • Pan via scroll (no modifier) and pointer drag
  • Multi-touch pinch-to-zoom with centroid tracking
  • Right-click detection (no pan on right-click)
  • Node dragging with viewport.zoom compensation and drag threshold
  • macOS trackpad magnification via Apple EAWT reflection (Desktop)
  • Platform bridge abstraction for desktop-specific gestures

Edge Rendering

  • Bezier paths with smart tangent distance and collinear bias
  • Orthogonal (step) paths
  • Arrow markers (open + closed)
  • Per-edge render styles (color, width, alpha)

JS/Web Interop

  • Karakum-generated TypeScript externals for @xyflow/react
  • Bidirectional conversion between common models and react-flow JS objects
  • Full external declarations for all react-flow components
  • Hook wrappers: useNodesState, useEdgesState, useReactFlow, useViewport, useOnViewportChange, useOnSelectionChange, useStore

Theme System

Complete dark-theme color token palette (FlowTokens.kt) and comprehensive sizing constants for every element (FlowSizing.kt).

Tests & Tracking

  • FlowChangesTest — addEdge deduplication, applyNodeChanges, applyEdgeChanges
  • parity/features.json with structured parity matrix and Gradle reportParity task

03 Reaktor Flow — The Bridge Layer

Package: dev.shibasis.reaktor.flow
Dependencies: compose-flow + reaktor-graph

reaktor-flow is a specialized adapter that transforms reaktor-graph Graph objects into compose-flow visual representations. It has four sub-systems.

3a. Adapter Layer

FileResponsibility
ReaktorFlowBuilder.ktTraverses a Graph, creates GraphNodeLayout records with position/size, converts to compose-flow Node/Edge lists
ReaktorFlowAssembly.ktResolves edges from graph semantics: attachment, navigation, data, and containment edges
ReaktorFlowMeasurement.ktText-based width/height measurement (character counting × charWidthPx)
ReaktorFlowPorts.ktMaps graph node types to ReaktorNodeKind, assigns port colors
ReaktorFlowLabels.ktDerives display labels, handles UUID detection
ReaktorFlowLayoutPolicy.ktGraph root route detection

3b. Layout Engine

BlueprintReaktorGraphLayoutStrategy implements a sophisticated lane-based layout:

  • Services in left column(s)
  • Routes in middle column(s) with attached screens to the right
  • Standalone screens below
  • Containers at bottom with nested child graphs
  • Adaptive column counts based on node count thresholds
  • Region boxes around graph boundaries with recursive layout for nested graphs

3c. Editor / Render Layer

FileResponsibility
ReaktorGraphEditor.ktTop-level editor with keyboard shortcuts (Cmd+/− zoom), focus management
ReaktorGraphCanvas.ktOrchestration boundary — creates ReactFlowState, delegates to scene
ReaktorGraphScene.ktWires everything: nodes/edges state, configures ReactFlow() with graph-specific types, styles, overlays
ReaktorGraphSceneState.ktSyncs graph changes, handles initial framing with delay, preserves dragged positions across rebuilds
ReaktorGraphViewport.ktGraph-specific fit-view with readable zoom bias, right-inset compensation
ReaktorGraphOverlays.ktChrome composition: toolbar, legend, minimap, region overlays

Render Components

  • ReaktorGraphNodeCard — Rich node cards with kind-colored title bar, port rows with dots/labels, root badge, hidden port counters
  • ReaktorGraphToolbar — Zoom controls, graph label, node/edge counts
  • ReaktorGraphLegend — Filterable node-kind legend with highlight support
  • ReaktorGraphMiniMap — Custom minimap with viewport indicator and kind-colored nodes
  • ReaktorGraphRegions — Dashed-border region boxes with label chips

3d. Type System

TypeValues / Fields
ReaktorNodeKindScreen (green), Route (blue), Container (purple), Service (orange), Node (gray) — each with title/body/border colors
ReaktorEdgeKindAttachment, Navigation, Data, Containment — each with accent color
ReaktorGraphNodeDatanodeId, title, subtitle, graphLabel, isRootNode, port lists & counts, kind
ReaktorGraphEdgeDatakind, label
ReaktorGraphRegionlabel, id, position, dimensions, color, depth
ReaktorFlowGraphComplete snapshot: nodes, edges, regions, lookup maps (graphNodes, flowIdsByNode, graphIdsByNode, graphs), style

3e. Style System

ReaktorGraphStyle is a comprehensive tuning object with nested configs:

Canvas

Background, chrome, text colors, fonts

Layout

Column/row gaps, compact gaps, group gaps

Node

Min width, title sizing, badge sizing, padding

Port

Row height, font sizing, handle offsets, preview rows

Region

Content padding, child gaps, frame insets, label styling

Chrome

Overlay padding, panel radius, minimap sizing

Viewport

Zoom bounds, readable zoom bias, startup delay

WidthPolicy

Per-node-type width multipliers

~100 tunable parameters in total.

04 Parity Snapshot

~35%

Estimated feature parity with react-flow

25

Parameters on ReactFlow() composable

5

Hooks / composable state accessors

~60

Missing react-flow props & callbacks

Core insight: compose-flow today is closer to a flow viewer than a flow editor. The data model and rendering are solid, but the defining editor interactions — drag-to-connect, edge interaction, multi-selection — are the critical missing pieces.

05 Detailed Gap Analysis

CategoryFeatureStatus
Node FeaturesCore node model (id, position, data, type, handles, zIndex)Done
Custom node types via nodeTypesDone
Node dragging with zoom compensationDone
Node click handlerDone
Node measurement & dimension reportingDone
draggable per-node flagMissing
selectable / connectable / deletable per-nodeMissing
extent / "parent" constraintMissing
expandParentMissing
origin (node anchor point)Missing
Built-in input / output / group typesMissing
Node resizingMissing
Keyboard navigation / accessibilityMissing
All remaining node events (doubleClick, drag start/stop, mouse enter/move/leave, contextMenu)Missing
Edge FeaturesBezier edge renderingDone
Orthogonal (step) edge renderingDone
Arrow markers (open + closed)Done
Per-edge render stylesDone
straight / smoothstep / simplebezier edge typesMissing
markerStartMissing
Edge click / hover / selection interactionMissing
Edge reconnectionMissing
interactionWidthMissing
Rich label content (not just String)Missing
ConnectiononConnect callbackPartial
Drag-to-connect (handle-to-handle)Missing
Connection line rendering during dragMissing
isValidConnection callbackMissing
Click-to-connect modeMissing
connectionRadius / connectionModeMissing
SelectionSingle node/edge selection trackingDone
Multi-select (shift+click)Missing
Rubber-band selection boxMissing
onSelectionChangeMissing
Selection dragMissing
DeletionKeyboard deleteMissing
onDelete / onBeforeDeleteMissing
Configurable deleteKeyCodeMissing
ViewportPan (drag, scroll, wheel)Done
Zoom (wheel, ctrl+scroll, pinch)Done
Fit viewDone
Programmatic zoom/pan/centerDone
Snap-to-gridMissing
translateExtent (viewport bounds)Missing
Controlled viewport modeMissing
Viewport culling (onlyRenderVisibleElements)Missing
Zoom on double-clickMissing
Auto-pan on drag near edgeMissing
ComponentsBackground (dots, lines, cross)Done
ControlsDone
MiniMapDone
PanelDone
NodeResizer / NodeToolbarMissing
BaseEdge / EdgeLabelRendererMissing
Hooks / APIState management (NodesState, EdgesState, ReactFlowState)Done
screenToFlowPositionDone
flowToScreenPositionMissing
Imperative methods (addNodes, deleteElements, getIntersectingNodes)Missing
useConnection, useHandleConnections, useNodeId, useKeyPressMissing
PlatformDesktop platform bridge (macOS trackpad, AWT scroll anchor)Done
JS/Web react-flow interop bridgePartial

06 Architecture Diagram

reaktor-graph
Graph, RouteNode, ContainerNode, PortGraph, BackStack
↓
reaktor-flow / adapter
traverse • measure • layout • assemble edges
↓
ReaktorFlowGraph
compose-flow Node/Edge + ReaktorGraphNodeData + Regions
↓
reaktor-flow / editor
ReaktorGraphScene → compose-flow ReactFlow()
↓
Compose (Android / iOS / Desktop)
react-flow (Web / JS)

07 Roadmap to Parity

Phase 1 — Core Interactions (Month 1–2)

  1. Drag-to-connect — The defining flow-editor interaction. Connection line rendering during drag, handle hit-testing, isValidConnection, onConnect/onConnectStart/onConnectEnd.
  2. Edge interaction — Click, hover, selection on edges. Options: hit-test on Canvas paths, invisible wider interaction overlay, or Modifier-based rendering.
  3. Multi-selection — Shift+click to toggle, rubber-band selection box, onSelectionChange.
  4. Keyboard delete — Delete/Backspace to remove selected nodes/edges. onDelete/onBeforeDelete.
  5. More edge types — straight, step, smoothstep. Path generation functions are straightforward.

Phase 2 — Node Constraints & Polish (Month 2–3)

  1. Per-node flags — draggable, selectable, connectable, deletable on individual nodes/edges.
  2. Node extent / parent constraints — extent: "parent", expandParent. Critical for sub-flows.
  3. Edge reconnection — Drag existing edge endpoint to new handle.
  4. Snap-to-grid — Grid alignment during drag.
  5. Auto-pan — Pan viewport when dragging near canvas edges.

Phase 3 — Advanced Features (Month 3–4)

  1. Node resizer — Drag handles on node corners/edges to resize.
  2. Controlled viewport — viewport/onViewportChange pair for external control.
  3. Viewport culling — Only render visible nodes/edges for large graphs.
  4. Full imperative API — Match useReactFlow() method surface.
  5. Keyboard navigation — Tab through nodes/edges, Enter to select.

Phase 4 — Full Parity (Month 4–5)

  1. NodeToolbar, EdgeLabelRenderer, BaseEdge components
  2. Connection modes (strict/loose), click-to-connect
  3. Z-index modes (basic/group)
  4. Color mode (light/dark switching)
  5. All remaining event callbacks (~25 missing)

08 Architectural Strengths Already in Place

Clean Separation

model (common) → runtime (common) → compose rendering (common) → platform bridges (per-target)

Immutable Data

@Immutable annotations on all models. Change-based state updates, not direct mutation.

JS Interop

Karakum-generated externals bridge to real react-flow on web. Bidirectional model conversion.

Platform Bridge

Abstraction for desktop-specific gestures. macOS trackpad already integrated via EAWT reflection.

Parity Tracking

parity/features.json with structured matrix and Gradle reportParity task built in.

Comprehensive Theming

Token-based color palette and ~60 sizing constants. Mirrors Fluent/React design-token patterns.

What reaktor-flow Needs Next

NeedDescription
Bidirectional editingCurrently read-only visualization. Needs to support node creation/deletion, edge creation, and propagate changes back to reaktor-graph.
Web parity via JS targetjsMain in compose-flow has react-flow interop, but reaktor-flow doesn’t have JS-specific code yet. Needed for Manna’s web app.
Graph mutation APIReaktorFlowGraph is a snapshot. Need a mutable controller that can addNode(), removeNode(), addEdge(), removeEdge() and sync back to Graph.
Layout algorithm pluggabilityOnly BlueprintReaktorGraphLayoutStrategy exists. Need force-directed, hierarchical (dagre-like), and manual layout options.
SerializationSave/restore graph layouts and viewport state.