reaktorWeb → reaktor-graph

1. Situation & Goals

What exists today

reaktorWeb is a React 19 workbench deployed on Cloudflare Workers. It has 10 modes (graph, agent, database, auth, deploy, insights, etc.), complex state management via a single React context (ScenarioContext — 762 lines), hash-based routing, mock services, and @xyflow/react graph visualization. Everything runs on hardcoded mock data.

reaktor-graph is a Kotlin Multiplatform graph framework with a mature JS target:

• WebHost — entry point wrapping a Graph with WebNavigationBridge
• StateFlow.toReactState() — bidirectional Kotlin StateFlow ↔ React useState bridge
• ReactNode<State> — Kotlin wrapper making React components act as graph nodes
• ReactContainer / ReactContent — interfaces for graph-driven rendering
• WebBottomNavigationContainer / WebTabbedContainer — container implementations
• GraphContentComponent — FC that renders based on backStack top entry
• @JsExport throughout, karakum TypeScript type generation

Goals

2. Polyglot Graph Design

reaktor-graph is Kotlin Multiplatform, but the website is React/TypeScript. The polyglot bridge must feel natural in both languages.

2.1 Current JS Target Surface

These are already @JsExported and proven:

2.2 TypeScript Interop Architecture

The polyglot boundary has three layers:

2.3 React Hook API Design

These hooks are the TypeScript-facing API. They wrap the Kotlin/JS exports into idiomatic React patterns:

// reaktor-web/src/hooks/use-graph.ts
// React context holding the WebHost + Graph instance
const GraphContext = createContext<WebHost | null>(null)

export function GraphProvider({ graph, children }) {
  const host = useMemo(() => {
    const h = new WebHost(graph)
    h.start()
    return h
  }, [graph])

  useEffect(() => () => host.destroy(), [host])

  return <GraphContext.Provider value={host}>{children}</GraphContext.Provider>
}

export function useGraph(): WebHost {
  return useContext(GraphContext)!
}

// reaktor-web/src/hooks/use-port.ts
// Subscribe to a ProviderPort's StateFlow value by port key
export function usePort<T>(nodeLabel: string, portKey: string): T {
  const host = useGraph()
  const node = host.graph.findNode(nodeLabel)
  const port = node.findProvider(portKey)
  // port.impl is a StateFlow — toReactState() bridges it
  const [value] = port.impl.toReactState()
  return value as T
}

// reaktor-web/src/hooks/use-navigation.ts
export function useNavigation() {
  const host = useGraph()
  return {
    push: (pattern: string, params?: Record<string, string>) =>
      host.navigateToPattern(pattern, params),
    pop: () => host.goBack(),
    topPattern: () => host.topPattern(),
    stackSize: () => host.stackSize(),
  }
}

2.4 Kotlin Exports Needed

New @JsExport additions required on reaktor-graph:

3. In-Memory Reactive Store

reaktorWeb needs cross-cutting state: selectedId, graphFocus, edgeFilters, theme, notifications, etc. Currently this is a React context god object. We need a graph-native replacement.

3.1 Design Principles

3.2 Architecture

3.3 Store Node Implementation

// reaktor-graph commonMain — new file
// dev/shibasis/reaktor/graph/store/MemoryStore.kt

@JsExport
class MemoryStore(graph: Graph) : BasicNode(graph) {
    private val slots = mutableMapOf<String, MutableStateFlow<Any?>>()

    // Create a typed slot and register it as a ProviderPort
    fun <T> slot(key: String, initial: T): MutableStateFlow<T> {
        val flow = MutableStateFlow<Any?>(initial)
        slots[key] = flow
        registerProvider(
            Port.KeyType(Port.Key(key), Port.Type(key)),
            flow
        )
        @Suppress("UNCHECKED_CAST")
        return flow as MutableStateFlow<T>
    }

    // Read-only access for JS interop
    fun get(key: String): Any? = slots[key]?.value
    fun set(key: String, value: Any?) { slots[key]?.value = value }
    fun flow(key: String): StateFlow<Any?>? = slots[key]

    // Batch update — mutate multiple slots atomically
    fun update(block: (slots: MutableMap<String, Any?>) -> Unit) {
        val snapshot = slots.mapValues { it.value.value }.toMutableMap()
        block(snapshot)
        snapshot.forEach { (key, value) -> slots[key]?.value = value }
    }
}

3.4 Store Slot Types (Kotlin — shared by both renderers)

// Common state types — used by engine and website
@Serializable
data class SelectionState(
    val selectedId: String? = null,
    val graphFocus: GraphFocus = GraphFocus.NONE,
    val edgeFilters: Set<String> = emptySet(),
)

@Serializable
data class LayoutState(
    val drawerOpen: Boolean = true,
    val drawerHeight: Int = 260,
    val drawerTab: String = "cmds",
    val leftWidth: Int = 240,
    val rightWidth: Int = 300,
    val leftCollapsed: Boolean = false,
    val rightCollapsed: Boolean = false,
)

@Serializable
data class EnvironmentState(
    val project: String = "bestbuds",
    val environment: String = "staging",
    val deviceTarget: String = "iPhone 16 Pro",
    val locale: String = "en",
    val themeMode: String = "dark",
    val networkMode: String = "online",
)

@Serializable
enum class GraphFocus { NONE, SELECTED, TRACE, BLAST, TESTS }

3.5 TypeScript Access via React Hooks

// useStore hook — typed access to MemoryStore slots
export function useStore<T>(key: string): [T, (value: T) => void] {
  const host = useGraph()
  const store = host.graph.findNode('store') as MemoryStore
  const flow = store.flow(key)
  const [value] = flow.toReactState()
  const setter = useCallback((v: T) => store.set(key, v), [store, key])
  return [value as T, setter]
}

// Usage in a React component
function GraphScreen() {
  const [selection, setSelection] = useStore<SelectionState>('selection')
  const [layout] = useStore<LayoutState>('layout')

  const onNodeClick = (nodeId: string) => {
    setSelection({ ...selection, selectedId: nodeId })
  }
  // ...
}

3.6 How This Relates to the Object Database

4. Navigation Topology

4.1 Current: Hash-Based Mode Switching

// scenario.jsx — mode is just a React state string
const [mode, setMode] = useState('graph')
// Cmd+1 → setMode('graph'), Cmd+2 → setMode('devtools'), etc.
// Agent sub-routes: #agent/conversation/{id}, #agent/scout/{id}, etc.

4.2 Target: Graph Navigation with URL Sync

4.3 URL Mapping

WebNavigationBridge handles all browser history sync — pushState on forward navigation, popstate listener for back button. The Cloudflare Worker's SPA fallback (not_found_handling: "single-page-application") already handles server-side routing.

5. State Decomposition

The ScenarioContext god object (40+ fields, 762 lines) must decompose into graph-native state. Each domain gets its own node with typed state exposed via ports.

5.1 Decomposition Map

5.2 Before/After Comparison

// scenario.jsx
function GraphScreen() {
  const sc = useScenario()
  // sc has 40+ fields
  // Re-renders on ANY change
  const { selectedId, graphFocus,
    edgeFilters, mode, drawerOpen,
    agents, dbTier, authView,
    ... } = sc
}

// screen-graph.tsx
function GraphScreen() {
  const [sel] = useStore<SelectionState>('selection')
  const nav = useNavigation()
  // Only re-renders when selection changes
  // No dependency on agent/db/auth state

  const onNodeClick = (id: string) =>
    setSelection({ ...sel, selectedId: id })
}

6. Service Modeling

6.1 Current Mock Services

// mock-services.js — 82 lines of setTimeout-based mocks
createMockWorkbenchServices() {
  hotReload({ device })              → wait(420ms)
  commitBundle({ bundleId, branch }) → wait(520ms)
  deploy({ env, bundleId })          → wait(650-900ms)
  rollback({ version, env })         → wait(600ms)
  runTests({ count })                → wait(760ms)
  sendToAgent({ bundleId })          → wait(450ms)
}

6.2 Target: ServiceNode with Typed Handlers

// commonMain — shared between engine and web
class WorkbenchService : Service() {
    val hotReload = PostHandler.create<HotReloadRequest, StatusResponse>(
        "/workbench/hot-reload", "HotReload"
    ) { request ->
        delay(420) // mock for now, real impl later
        StatusResponse(statusCode = StatusCode.OK)
    }

    val commitBundle = PostHandler.create<CommitRequest, StatusResponse>(
        "/workbench/commit", "CommitBundle"
    ) { request ->
        delay(520)
        StatusResponse(statusCode = StatusCode.OK)
    }

    val deploy = PostHandler.create<DeployRequest, DeployResponse>(
        "/workbench/deploy", "Deploy"
    ) { request ->
        delay(if (request.env == "production") 900 else 650)
        DeployResponse(statusCode = StatusCode.OK, version = "1.0.${revision++}")
    }
    // ... rollback, runTests, sendToAgent
}

Each handler becomes a ProviderPort on the ServiceNode. React components consume them via the useService hook:

// TypeScript usage
function DeployPanel() {
  const deploy = useService('workbench-svc', 'Deploy')
  const [env] = useStore<EnvironmentState>('environment')

  const handleDeploy = async () => {
    const response = await deploy({ env: env.environment, bundleId: currentBundle })
    // response is typed DeployResponse
  }
}

7. Self-Referential Visualization

The most powerful outcome: the graph screen shows the app's own live graph.

7.1 Data Pipeline

7.2 What Gets Visualized

7.3 Replacing Hardcoded Data

// scenario.jsx — 80+ entities
const ENTITIES = {
  'route:/onboarding': {
    type: 'route', title: '/onboarding',
    pos: { x: COL_0, y: ROW_0, w: 420, h: 140 },
    ports: { in: ['NavBinding'], out: ['routeBinding'] },
    ...
  },
  // 79 more...
}
const EDGES = [ /* 40+ edges */ ]
const REGIONS = [ /* 6 regions */ ]

// screen-graph.jsx
const flowData = scenarioToFlowData(ENTITIES, EDGES, REGIONS)

// screen-graph.tsx
function GraphScreen() {
  const host = useGraph()
  const style = defaultReaktorGraphStyle()

  const flowData = useMemo(() => {
    const flowGraph = buildReaktorFlowGraph(
      host.graph, style
    )
    return flowGraph.toReactFlowData()
  }, [host.graph, /* revision trigger */])

  return <ReactFlow
    nodes={flowData.nodes}
    edges={flowData.edges}
    nodeTypes={nodeTypes}
  />
}

8. Dual Renderer Architecture

The graph definition is shared. Two renderers consume it independently.

8.1 Module Layout

8.2 Shared Graph Definition

The workbench graph definition lives in a shared module (or in the engine module's commonMain) so both renderers consume the same topology:

// commonMain — shared graph builder
@JsExport
fun buildWorkbenchGraph(
    dependencyAdapter: DependencyAdapter? = null
): Graph {
    val graph = Graph(
        label = "workbench",
        dependencyAdapter = dependencyAdapter
    )

    // Store
    val store = MemoryStore(graph).apply {
        slot("selection", SelectionState())
        slot("layout", LayoutState())
        slot("environment", EnvironmentState())
        slot("system", SystemState())
    }
    graph.attach(store)

    // Routes
    val graphRoute = graph.Route("/graph")
    val devtoolsRoute = graph.Route("/devtools")
    val agentRoute = graph.Route("/agent")
    val uiRoute = graph.Route("/ui")
    val databaseRoute = graph.Route("/database")
    val authRoute = graph.Route("/auth")
    val aiRoute = graph.Route("/ai")
    val testingRoute = graph.Route("/testing")
    val deployRoute = graph.Route("/deploy")
    val insightsRoute = graph.Route("/insights")

    // Agent container with child graph
    val agentContainer = AgentContainer(graph, "/agent", mapOf(
        "chat" to ChildGraph(/* ... */),
        "scout" to ChildGraph(/* ... */),
        "queue" to ChildGraph(/* ... */),
        "manage" to ChildGraph(/* ... */),
        "pipeline" to ChildGraph(/* ... */),
    ))

    // Services
    val workbenchSvc = ServiceNode(graph, WorkbenchService())
    val agentSvc = ServiceNode(graph, AgentService())
    graph.attach(workbenchSvc)
    graph.attach(agentSvc)

    // Wiring
    graph.autoWire()

    // Default route
    graph.addRoot(graphRoute, Payload())

    return graph
}

8.3 Renderer-Specific Wiring

// main.jsx
import { buildWorkbenchGraph } from 'reaktor-kt'

const graph = buildWorkbenchGraph()

// Attach React nodes (web-specific)
attachReactScreens(graph)

// Start
const host = new WebHost(graph)
host.start()

ReactDOM.createRoot(root).render(
  <GraphProvider graph={graph}>
    <AppShell />
  </GraphProvider>
)

// Desktop main.kt
fun main() = application {
  val graph = buildWorkbenchGraph(
    KoinDependencyAdapter()
  )

  // Attach Compose nodes (desktop-specific)
  attachComposeScreens(graph)

  // Render
  Window(title = "Reaktor") {
    GraphApplication(graph)
  }
}

9. Migration File Map

9.1 New Kotlin Files (commonMain — shared)

9.2 New Kotlin Files (jsMain — web bridge)

9.3 New TypeScript/React Files

9.4 Modified React Files

10. Sprint Plan

11. Risk Matrix

Summary

The migration transforms reaktorWeb from a standalone React app with hardcoded mock data into a polyglot reaktor-graph application with:

• Typed graph model shared between desktop and web
• Reactive in-memory store built on ports and StateFlow
• URL-based navigation synced with browser history
• Typed services replacing mock timeouts
• Self-referential visualization — the app is its own graph
• Better performance — per-slot subscriptions replace god-object context

This is the highest-value stress test for reaktor-graph. If the framework can power a 14K-line workbench with 10 modes, nested navigation, cross-cutting state, services, and self-visualization — it can power anything.