Reaktor DocsArchitectureClaude

Architecture · Claude

Framework Architecture Analysis

Deep architecture notes on PortGraph, KMP execution, edge caching, FFI, and app DX.

Use whenUse for broad architecture review and idea inventory.
SourceClaude
Route/docs/architecture-analysis

Part 1: Graph Engine & KSP Compilation (Points 1 - 20)

The Bottleneck

Traditional visual node editors and graph-based architectures heavily rely on runtime reflection to dynamically resolve port types, instantiate nodes, and bind edges. In Kotlin Multiplatform (especially Kotlin/Native for iOS), runtime reflection is severely constrained, heavily penalizes startup performance, and leads to fragile architectures prone to `ClassCastException` and `NoSuchMethodError` crashes at runtime. Dynamic port bindings prevent proactive error detection, shifting validation burdens onto the developer during UI interaction rather than compile time.

Disruptive Solution

Reaktor entirely bypasses runtime reflection by utilizing Kotlin Symbol Processing (KSP) to synthetically generate the entire graph definition and routing infrastructure at compile time. By annotating nodes, Reaktor's KSP processor statically analyzes the source code, validates port type compatibility, detects acyclic topologies, and generates strongly-typed edge routers. This means the computational cost of resolving graph logic is pushed to the compiler, resulting in zero-overhead instantiation and execution across all KMP targets.

Architectural Implementation

// Node definition with annotations
@ReaktorNode(name = "StringLength")
class StringLengthNode : Node() {
    @InputPort
    val inputString = Port<String>()
    
    @OutputPort
    val lengthOut = Port<Int>()
    
    override suspend fun evaluate() {
        lengthOut.emit(inputString.value.length)
    }
}

// Generated by KSP: Type-safe router
object ReaktorGeneratedGraphRouter {
    fun route(source: Port<*>, target: Port<*>) {
        // Static dispatch, no reflection
        if (source is StringPort && target is StringPort) {
            target.value = source.value
        }
    }
}

Ecosystem Impact

This approach radically shifts the paradigm of visual node editors in the Kotlin ecosystem. It allows Reaktor to run exceptionally fast on iOS (Kotlin/Native) and JS/Wasm environments where reflection is absent or highly penalized. The resulting architecture guarantees type safety, fundamentally preventing graph execution crashes and accelerating Developer Experience (DX) via instant compile-time feedback.

The Bottleneck

In dataflow architectures, propagating state changes between thousands of nodes typically involves creating intermediate message objects, events, or lambda allocations. In a high-frequency graph (e.g., 60fps UI updates or audio processing), this continuous instantiation strains the Garbage Collector (GC), causing unpredictable UI stuttering and frame drops on memory-constrained mobile devices and browser environments.

Disruptive Solution

Reaktor utilizes a zero-allocation routing bus. Instead of dispatching events, edges act as direct memory pointers (in K/N) or strongly-referenced delegates. State transitions are propagated via pre-allocated mutable state holders. When an output port mutates, it directly invokes a pre-compiled function pointer array or statically dispatched method to update connected input ports, triggering evaluations without instantiating single-use event envelopes.

Architectural Implementation

// Zero-allocation port propagation
abstract class Port<T> {
    var value: T = uninitialized()
        set(newValue) {
            field = newValue
            // Array traversal, no iterator allocation
            for (i in 0 until listenersCount) {
                listeners[i].onValueChanged(newValue)
            }
        }
}

Ecosystem Impact

By eradicating allocations during the hot path of graph execution, Reaktor sustains perfectly flat memory usage profiles. This is critical for Compose Multiplatform, as predictable memory pressure ensures smooth UI rendering without intermittent GC pauses, establishing Reaktor as a viable engine for real-time mobile and edge processing.

The Bottleneck

Complex node graphs often suffer from the "glitch" problem (or redundant evaluations) where a node is evaluated multiple times in a single logical tick because its inputs arrive asynchronously or sequentially. This non-deterministic resolution wastes computational cycles and can cause intermediate invalid states to ripple through the system, confusing users and corrupting data.

Disruptive Solution

Reaktor implements a deterministic topological sorting execution model per tick. When an external input changes, the engine marks the impacted node as dirty. Instead of immediately evaluating it, Reaktor traverses the graph to build a dirty set, topologically sorts the dependencies, and executes them in a single, strictly ordered pass. Each node evaluates exactly once per frame, guaranteeing consistent and synchronous state projection.

Architectural Implementation

class GraphEngine {
    fun tick() {
        val sortedNodes = topologicalSort(dirtyNodes)
        for (node in sortedNodes) {
            if (node.areAllInputsReady()) {
                node.evaluateSync()
                node.markClean()
            }
        }
    }
}

Ecosystem Impact

This deterministic approach eliminates race conditions inherent in reactive streams. It provides absolute predictability, simplifying debugging significantly. Developers can rely on Reaktor for mission-critical state management where transient, intermediate states could result in fatal business logic errors, offering a level of stability not found in standard Rx/Flow architectures.

The Bottleneck

Visual editors allow users to modify graph topology on the fly—adding nodes, removing edges, or restructuring logic. Recompiling or resetting the entire graph engine upon every edit destroys active session state, drops network connections, and provides a jarring user experience. Hot-reloading stateful graph architectures is incredibly complex.

Disruptive Solution

Reaktor employs a dynamic Graph Topology Diffing algorithm, conceptually similar to React's Virtual DOM but applied to node execution logic. When a new graph configuration is submitted (e.g., from the visual IDE), Reaktor computes the minimal set of structural changes (insertions, deletions, edge mutations) and applies these patches to the running graph *without* halting active node evaluations or losing the internal state of untouched nodes.

Architectural Implementation

fun applyGraphDiff(oldGraph: Graph, newGraph: Graph) {
    val diff = GraphDiffer.compute(oldGraph, newGraph)
    
    diff.removedNodes.forEach { engine.destroyNode(it) }
    diff.addedNodes.forEach { engine.initializeNode(it) }
    diff.edgeChanges.forEach { change -> 
        engine.rebind(change.source, change.target) 
    }
    
    // Retain state for unmodified nodes automatically
}

Ecosystem Impact

This achieves seamless hot-reloading for business logic. In a visual IDE context, developers can literally rewire live applications, observing the data flow change in real-time without losing their current application state. It elevates Reaktor from a static configuration tool to an interactive, live-programming environment.

The Bottleneck

Traditional dataflow graphs execute synchronously. Incorporating asynchronous operations like API calls, database reads, or disk I/O requires hacking the graph with complex promise-chaining or external callback orchestrators, which breaks the visual mental model and scatters logic.

Disruptive Solution

Reaktor nodes are natively built on Kotlin Coroutines. The `evaluate` function of a node is a `suspend` function. The graph engine orchestrator is a highly specialized Coroutine dispatcher that manages the execution context of each node. Nodes can seamlessly perform non-blocking I/O, and the engine correctly pauses the propagation for that specific subgraph branch until the suspension completes, while allowing independent branches to continue processing concurrently.

Architectural Implementation

@ReaktorNode
class NetworkFetchNode : Node() {
    val url = InputPort<String>()
    val response = OutputPort<String>()
    
    override suspend fun evaluate() {
        // Non-blocking suspension natively integrated
        val data = httpClient.get(url.value).bodyAsText()
        response.emit(data)
    }
}

Ecosystem Impact

By treating suspension as a first-class citizen, Reaktor cleanly bridges visual node programming with modern asynchronous network demands. It enables developers to design complex asynchronous orchestrations visually without drowning in callback hell or manual Coroutine scope management, solidifying its use case for Edge/Cloudflare orchestration.

The Bottleneck

Allowing users to connect graph outputs back into upstream inputs creates cyclic dependencies. Unmanaged, this leads to infinite evaluation loops (stack overflows) or coroutine deadlocks, crashing the application instantly.

Disruptive Solution

Reaktor introduces explicit "Delay" or "Feedback" nodes designed to break cycles by deferring the emission to the next tick cycle. Furthermore, the KSP compiler and runtime topology validator actively detect implicit cycles. If a cycle is formed without a designated Delay node, the connection is either rejected at compile time (if static) or safely disabled at runtime, visually alerting the user via the IDE rather than crashing.

Architectural Implementation

fun validateTopology(nodes: List<Node>) {
    val cycle = detectCycle(nodes)
    if (cycle != null && !cycle.any { it is DelayNode }) {
        throw InvalidGraphTopologyException("Unbroken cycle detected: $cycle")
    }
}

Ecosystem Impact

This strict topology enforcement guarantees absolute stability of the graph engine. It allows developers to implement complex feedback loops (essential for state machines, physics simulations, or iterative algorithms) safely, bringing industrial-grade control systems concepts into standard app development.

The Bottleneck

When multiple nodes share a reference to a mutable object passed through a port (e.g., a shared MutableList), one node mutating the object will unpredictably affect downstream or upstream nodes, destroying the integrity of the dataflow and violating the encapsulation of the node.

Disruptive Solution

Reaktor enforces deep immutability at the port boundary. Values emitted through ports must either be primitives, Kotlin data classes consisting of immutable properties, or wrapped in immutable collections (e.g., `kotlinx.collections.immutable`). Reaktor's KSP processor issues compilation errors if mutable collections are declared as Port types. For large objects, Reaktor uses structural sharing.

Architectural Implementation

// KSP Validation Logic
if (portType.isMutableCollection()) {
    kspLogger.error("Ports must use immutable data structures to prevent side-effects.")
}

// Correct Usage
val listPort = Port<PersistentList<String>>()

Ecosystem Impact

This functional programming mandate ensures that the visual representation of dataflow exactly matches execution reality. It prevents insidious bugs caused by shared mutable state across complex graphs, making Reaktor architectures exceptionally reliable and easy to parallelize without thread-safety concerns.

The Bottleneck

Executing massive graphs on a single thread bottlenecks the entire application, failing to utilize modern multi-core processors. However, executing nodes concurrently often leads to race conditions if dependencies aren't strictly respected.

Disruptive Solution

Reaktor's graph analyzer identifies isolated subgraphs or parallel execution branches that do not share direct data dependencies. Using Kotlin Coroutines, the engine dynamically dispatches these independent subtrees to parallel worker threads (e.g., `Dispatchers.Default`). A synchronization barrier ensures that nodes waiting on multiple parallel branches only execute when all upstream dependencies have resolved safely.

Architectural Implementation

suspend fun evaluateConcurrent(nodes: List<Node>) = coroutineScope {
    val independentBranches = analyzeParallelism(nodes)
    independentBranches.map { branch ->
        async(Dispatchers.Default) {
            executeBranch(branch)
        }
    }.awaitAll()
}

Ecosystem Impact

Reaktor effortlessly transforms visual logic into highly parallelized, multi-core-aware software without requiring the user to write a single line of synchronization code. This is profoundly disruptive for processing-heavy applications like local LLM routing, image processing, or big-data aggregation on edge devices.

The Bottleneck

In many visual node editors, ports are untyped or dynamically typed at runtime. Attempting to connect a string output to an integer input either fails silently, causes runtime crashes, or requires heavy runtime coercion logic that masks architectural errors.

Disruptive Solution

Reaktor utilizes Kotlin's sophisticated generics system to strongly type every port. When defining the graph programmatically or parsing visual schemas, the compiler strictly enforces covariance and contravariance. An edge connecting `Port<String>` to `Port<Int>` will simply fail to compile. For the visual IDE, this type information is exported to constrain user interactions in the UI, physically preventing invalid connections.

Architectural Implementation

// Strongly typed edge creation
infix fun <T> OutputPort<T>.connectTo(input: InputPort<T>) {
    // Logic
}

// Compile error: Type mismatch
// stringOutput connectTo intInput

Ecosystem Impact

By pushing data validation to the compiler, Reaktor guarantees that graphs deployed to production are structurally sound. Developers trust that if the graph compiles, the data flow is logically consistent. This vastly accelerates development speed and lowers the barrier to entry for citizen developers using the IDE.

The Bottleneck

Monolithic graph architectures become visually unmanageable and computationally bloated. Loading all possible application logic into memory simultaneously degrades performance and makes modular development impossible.

Disruptive Solution

Reaktor introduces the concept of dynamically loadable "Subgraph Nodes". These act as proxy nodes that can fetch, parse, and instantiate serialized subgraphs at runtime (from disk or network). Once loaded, the subgraph seamlessly integrates its inputs and outputs into the parent node, acting as a modular, lazy-loaded component.

Architectural Implementation

@ReaktorNode
class DynamicModuleNode : Node() {
    suspend fun loadModule(graphId: String) {
        val subgraph = graphRepository.fetch(graphId)
        this.internalGraph = engine.compile(subgraph)
        this.bindProxyPorts()
    }
}

Ecosystem Impact

Dynamic subgraph injection enables true micro-frontend and modular application architectures within Reaktor. Logic can be partitioned, updated over the air (OTA), and lazy-loaded, drastically reducing initial footprint and allowing massive, cloud-scale architectures to be managed visually in composable blocks.

The Bottleneck

Parsing JSON or XML graph definitions at startup on mobile devices involves heavy string manipulation, reflection, and memory allocation, leading to noticeable "white screen" delays before the application becomes interactive.

Disruptive Solution

Reaktor utilizes `kotlinx.serialization` combined with FlatBuffers or Protocol Buffers for graph definitions. Instead of parsing textual representation, Reaktor loads binary, memory-mapped graph definitions. The KSP compiler generates direct binary decoders, skipping the intermediate object tree generation and instantiating nodes directly from byte offsets.

Architectural Implementation

// Binary graph loader
fun loadGraphFromBinary(buffer: ByteBuffer): Graph {
    // Direct memory mapping, near zero parsing time
    val blueprint = GraphBlueprint.getRootAsGraphBlueprint(buffer)
    return engine.instantiate(blueprint)
}

Ecosystem Impact

This ultra-fast serialization strategy allows Reaktor apps to cold-boot in milliseconds. This is essential for Android/iOS applications where user retention drops sharply with startup delay, proving Reaktor is optimized for production mobile constraints, not just theoretical visual editing.

The Bottleneck

Maintaining parity between backend code nodes and the frontend visual IDE is a nightmare. Developers often must manually update JSON schemas to define node colors, categories, tooltips, and port names every time a Kotlin node changes, leading to inevitable desynchronization.

Disruptive Solution

Reaktor's KSP processor acts as a Single Source of Truth. Through specialized annotations (`@NodeColor`, `@PortDescription`), developers define visual metadata directly in the Kotlin source code. During compilation, KSP automatically generates the JSON/TypeScript schemas required by the web-based visual IDE. The IDE is always perfectly synchronized with the underlying KMP code.

Architectural Implementation

@ReaktorNode(category = "Math")
@NodeVisuals(color = "#FF5733", icon = "add_circle")
class AddNode : Node() {
    @PortDescription("The first operand")
    val a = InputPort<Float>()
}

Ecosystem Impact

This automated metadata extraction ensures zero drift between the engine and the editor. It dramatically improves DX, as backend engineers can define UI configurations directly within their domain, eliminating the need for context-switching or manual schema maintenance.

The Bottleneck

Debugging stateful logic requires logging, breakpoints, and manual state reconstruction. When a complex bug occurs in a multi-node system, standard step-through debuggers are useless because they don't capture the history of data flow and port emissions.

Disruptive Solution

Reaktor incorporates a lightweight, ring-buffered execution history. Every tick, the engine records a snapshot of port values. In the visual IDE, developers can pause execution and use a "slider" to step backward in time, visually observing the exact data flowing through the edges and the state of the nodes milliseconds prior to an error.

Architectural Implementation

class GraphHistoryBuffer(size: Int) {
    private val snapshots = RingBuffer<GraphSnapshot>(size)
    
    fun record(graph: Graph) {
        snapshots.add(graph.captureState())
    }
    fun restore(tick: Long): GraphSnapshot { ... }
}

Ecosystem Impact

Time-travel debugging fundamentally transforms the developer experience. It turns abstract logic errors into visually tangible events, drastically reducing the time spent tracking down elusive state bugs. This level of observability sets Reaktor apart as a premium, developer-first framework.

The Bottleneck

Wrapping primitive data types (like Int, Float, Boolean) in domain-specific objects (e.g., `Temperature(val celsius: Float)`) introduces significant heap allocation overhead when millions of data points pass through the graph.

Disruptive Solution

Reaktor deeply integrates Kotlin `value class` features. When domain concepts are modeled as value classes, the Kotlin compiler natively unboxes them to primitives at runtime. Reaktor's port generics respect this unboxing, ensuring that high-level domain semantics (Type Safety) can be passed through ports with zero allocation penalty (Primitive Performance).

Architectural Implementation

@JvmInline
value class Voltage(val v: Float)

@ReaktorNode
class SensorNode : Node() {
    // Typed as Voltage, but executes as raw primitive Float
    val output = OutputPort<Voltage>()
}

Ecosystem Impact

This allows developers to create highly expressive, domain-driven node networks without sacrificing raw computational power. Reaktor achieves the performance of C-style data processing arrays while maintaining the safety and expressiveness of high-level Kotlin abstractions.

The Bottleneck

Threading models are fundamentally different across platforms: JVM has thread pools, iOS/Native relies on Darwin GCD, and JS/Wasm runs strictly single-threaded event loops. Writing unified asynchronous graph logic is notoriously difficult.

Disruptive Solution

Reaktor abstracts all platform-specific threading behind a unified `ReaktorDispatcher` interface. Using Kotlin Multiplatform `expect/actual` mechanics, Reaktor Maps graph node execution strategies appropriately: utilizing multi-threading on JVM/Android, leveraging GCD on iOS, and seamlessly downgrading to cooperative event-loop chunking on JS/Wasm without changing a single line of node logic.

Architectural Implementation

// Common
expect val ReaktorIO: CoroutineDispatcher

// iOS Actual
actual val ReaktorIO = newFixedThreadPoolContext(4, "Reaktor-IO")

// JS Actual
actual val ReaktorIO = Dispatchers.Main // Single threaded fallback

Ecosystem Impact

This powerful abstraction ensures the "Write Once, Run Everywhere" promise of KMP is upheld for complex, concurrent dataflow logic. Developers can focus on the business rules within their nodes, trusting Reaktor to optimally execute them according to the target architecture's capabilities.

The Bottleneck

Typical RxJava or Flow implementations wrap emitted values in internal nodes (e.g., `Observable.OnNext`). Even a simple float emission requires a new object allocation. At 10,000 emissions per second, this thrashes the garbage collector.

Disruptive Solution

Reaktor utilizes state-mutating emissions rather than event streams. Ports contain direct references to a memory address or primitive field. When `.emit(value)` is called, Reaktor overwrites the existing value in memory and flags the port as dirty. No `Event` objects are instantiated, achieving a strictly garbage-free hot path.

Architectural Implementation

class FloatPort : Port<Float>() {
    var value: Float = 0f
    
    fun emit(newVal: Float) {
        this.value = newVal // Direct primitive overwrite
        markDirty()         // Flag manipulation, no allocation
    }
}

Ecosystem Impact

By guaranteeing zero allocations during value emission, Reaktor becomes suitable for embedded systems, high-frequency trading applications, and latency-critical game engines—domains traditionally reserved for C++ or Rust.

The Bottleneck

If a fast producer node (e.g., WebSockets) emits data faster than a slow consumer node (e.g., Database Writer) can process it, memory will exhaust as unhandled events pile up, leading to OutOfMemory errors.

Disruptive Solution

Reaktor edges natively support configurable backpressure strategies: Drop Latest, Drop Oldest, Buffer(size), or Suspend. Because Reaktor is coroutine-based, a fast producer can naturally be `suspended` by the framework if the downstream edge buffer reaches capacity, gracefully slowing down the entire upstream branch without manual intervention.

Architectural Implementation

@EdgeConfiguration(strategy = BackpressureStrategy.SUSPEND)
val dataStream = OutputPort<ByteArray>()

// Inside fast producer
suspend fun evaluate() {
    while(active) {
        // Will automatically suspend if consumer is slow
        dataStream.emit(readChunk()) 
    }
}

Ecosystem Impact

Native backpressure management simplifies complex asynchronous piping. It creates highly resilient systems that degrade gracefully under load rather than crashing violently, which is a key requirement for reliable Cloudflare Workers edge deployments.

The Bottleneck

Nodes holding open resources (network sockets, file handles, database connections) must release them when removed from the graph or when the app shuts down. Forgetting to clean up results in memory leaks and blocked ports.

Disruptive Solution

Reaktor enforces a strict lifecycle contract (`onCreate`, `onStart`, `onStop`, `onDestroy`) managed symmetrically by the Graph Engine. Nodes request resources via contextual scopes tied to their lifecycle. When a node is dynamically removed (via topology changes or shutdown), Reaktor automatically cancels its CoroutineScope and closes all associated scoped resources.

Architectural Implementation

class DatabaseNode : Node() {
    override fun onStart() {
        // Scope automatically cancelled onStop
        nodeScope.launch {
            connectToDb()
        }
    }
    override fun onDestroy() {
        // Cleanup logic
        dbConnection.close()
    }
}

Ecosystem Impact

Lifecycle automation entirely removes the burden of manual resource cleanup from the developer. It ensures that applications remain stable and memory-leak-free over long running sessions, a common pitfall in dynamic reactive systems.

The Bottleneck

Instantiating thousands of nodes for repeating UI elements (like list items) consumes massive memory if each node holds independent configuration metadata, logic, and state. This scaling limit hinders graph architectures from driving massive UIs.

Disruptive Solution

Reaktor decouples node logic (Stateless Template) from node state (Instance Data). A single `StringLengthNode` class logic exists in memory. When instantiated 1,000 times, Reaktor only allocates an array of state structures. The execution engine maps the stateless logic to the corresponding state slice during evaluation, achieving Flyweight pattern efficiencies.

Architectural Implementation

// Conceptual Engine Execution
val template = getTemplate(StringLengthNode::class)
val nodeStates = getStatesForType(StringLengthNode::class)

for (state in nodeStates) {
    // Execute logic passing in specific instance state
    template.evaluate(state)
}

Ecosystem Impact

By adopting Data-Oriented Design (DOD) principles under the hood, Reaktor's memory footprint is minimized, and CPU cache hits are maximized. This architecture allows graphs to comfortably scale to tens of thousands of active nodes, making it suitable for granular UI component state management.

The Bottleneck

In generic reactive frameworks, if one input out of five changes, the entire block of logic must re-execute, wasting CPU cycles re-computing unchanged data paths.

Disruptive Solution

Reaktor allows developers to define explicit triggering logic for ports. A port can be marked as a `Trigger` (forces evaluation) or `State` (silently updates without triggering). Furthermore, nodes can query exactly *which* ports triggered the evaluation, enabling micro-optimizations within the node to only process the specific delta.

Architectural Implementation

@ReaktorNode
class HeavyMathNode : Node() {
    // Triggers evaluation
    @InputPort(trigger = true)
    val mainData = Port<Matrix>()
    
    // Does NOT trigger, acts as reference state
    @InputPort(trigger = false)
    val configModifier = Port<Float>()
    
    override suspend fun evaluate() {
        // Only runs when mainData changes
    }
}

Ecosystem Impact

Granular control over execution paths gives developers fine-tuning capabilities previously unavailable in visual architectures. It guarantees that heavy computations are explicitly gated, providing superior battery life optimization on mobile devices using Reaktor.