React Flow Architecture Canvas: Nodes, Layout, and Undo

A generated architecture is useful only if you can challenge it. Move a boundary, rename a service, undo a bad idea. Codelit's canvas is where a model's suggestion becomes something an engineer can work with.

I spent more time on the canvas than on any other part of the product, which is fitting given that the whole thing started as a Lucidchart rage-quit. React Flow (@xyflow/react) made it possible without me having to build a rendering engine from scratch. But "possible" and "easy" are very different words.

React Flow won because I needed an editor made from React components, with selection and connection behavior already in place. Other libraries can support rich interactions, but React Flow reduced the amount of integration code between the graph and the rest of the application.

I did prototype the raw canvas version over a weekend. Drawing rectangles and lines was fine. Then I started listing what still had to exist before anyone could actually use the thing, and killed it.

The rest of the case for React Flow is unglamorous and decisive: pan, zoom, minimap, selection and keyboard shortcuts work out of the box; every node type, edge type and event handler is properly typed; and the maintainers at xyflow are active. I've opened 3 issues and all got responses within a day.

A Codelit node is a React component that renders an icon, a label, a metadata line, and the handles edges connect to. Everything it shows comes from the node's data object, including the status that decides whether it draws as healthy, degraded, or failed.

The example below shows a database node. Its status is diagram state, not a live health measurement unless a separate data source supplies one. The component can explain a simulation without pretending to monitor production.

import { Handle, Position, type Node, type NodeProps } from "@xyflow/react";

type DatabaseNodeData = {
  label: string;
  dbType: "postgres" | "mysql" | "mongodb" | "redis" | "dynamodb";
  replicas: number;
  status: "healthy" | "degraded" | "failed";
};

type DatabaseNodeType = Node<DatabaseNodeData, "database">;

function DatabaseNode({ data, selected }: NodeProps<DatabaseNodeType>) {
  return (
    <div className={`node-database ${data.status} ${selected ? "selected" : ""}`}>
      <Handle type="target" position={Position.Top} />

      <div className="node-icon">
        <DatabaseIcon type={data.dbType} />
      </div>
      <div className="node-label">{data.label}</div>
      <div className="node-meta">
        {data.dbType} &middot; {data.replicas} replica{data.replicas !== 1 ? "s" : ""}
      </div>

      {data.status === "failed" && <div className="failure-badge">FAILED</div>}

      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

That status field is what chaos mode drives when it kills a component and models how failure could spread. The visual state is useful because it is inspectable, not because it proves a real outage.

The current Codelit canvas registers one shared systemNode component and passes the infrastructure role through its data. Separate components are another valid design; the simplified example below shows how a larger library could register them.

Registering custom nodes with React Flow is straightforward:

const nodeTypes = {
  service: ServiceNode,
  database: DatabaseNode,
  api: APINode,
  queue: QueueNode,
  cache: CacheNode,
  loadBalancer: LoadBalancerNode,
  cdn: CDNNode,
  external: ExternalServiceNode,
};

function Canvas() {
  const { nodes, edges } = useCanvasStore();

  return <ReactFlow nodes={nodes} edges={edges} nodeTypes={nodeTypes} fitView />;
}

Codelit encodes traffic type in the edge itself: blue solid for synchronous HTTP calls, amber dashed for async queue messages, green dotted for pub/sub events. Users can tell at a glance which connections are sync and which are async without reading a single label.

Motion can suggest direction, but it must not imply observed traffic when the diagram has no telemetry source. This simplified edge treatment uses CSS rather than JavaScript per frame, and should respect reduced-motion preferences:

.react-flow__edge-path {
  stroke-dasharray: 8 4;
  animation: flowAnimation 1.5s linear infinite;
}

@keyframes flowAnimation {
  from {
    stroke-dashoffset: 24;
  }
  to {
    stroke-dashoffset: 0;
  }
}

@media (prefers-reduced-motion: reduce) {
  .react-flow__edge-path {
    animation: none;
  }
}

.edge-sync .react-flow__edge-path {
  stroke: #3b82f6; /* blue for synchronous */
}

.edge-async .react-flow__edge-path {
  stroke: #f59e0b; /* amber for async/queue-based */
  stroke-dasharray: 4 8; /* different dash pattern */
}

The AI returns a JSON structure describing components and their connections, and it knows nothing about pixel coordinates, visual spacing, or where anything belongs on a 1200x800 canvas. Converting that into a well-laid-out diagram was the hardest problem in the entire product.

Nothing upstream helps. The pipeline that produces that JSON deals in components and edges, not geometry, and the same problem lands on you whether the nodes arrived from a prompt or from Mermaid syntax pasted into the editor.

I explored several layout approaches. Their tradeoffs matter more than a rewrite count:

The current architecture canvas uses a smaller depth-based layout: find roots, walk outgoing edges with cycle bounds, assign fallback rows by type, and center each row. The concrete payoff is a predictable diagram without making layout another remote request.

Dagre is an alternative when a layered graph needs more control over ordering and spacing. This example shows its coordinate conversion; it is not the current Codelit layout implementation.

import dagre from "dagre";

function layoutNodes(nodes: Node[], edges: Edge[]): Node[] {
  const g = new dagre.graphlib.Graph();
  g.setDefaultEdgeLabel(() => ({}));
  g.setGraph({
    rankdir: "TB",
    nodesep: 80,
    ranksep: 100,
    marginx: 40,
    marginy: 40,
  });

  nodes.forEach((node) => {
    g.setNode(node.id, { width: 200, height: 80 });
  });

  edges.forEach((edge) => {
    g.setEdge(edge.source, edge.target);
  });

  dagre.layout(g);

  return nodes.map((node) => {
    const pos = g.node(node.id);
    return {
      ...node,
      position: { x: pos.x - 100, y: pos.y - 40 }, // center offset
    };
  });
}

Codelit's current version store records architecture objects with their prompt and timestamp, then tracks the active index. Adding a version removes any redo branch beyond that index. This makes supported domain edits recoverable without tying the history model to React Flow's rendering state.

The equivalent past-present-future pattern is useful to understand:

interface HistoryState {
  past: CanvasSnapshot[];
  present: CanvasSnapshot;
  future: CanvasSnapshot[];
  pushState: (snapshot: CanvasSnapshot) => void;
  undo: () => void;
  redo: () => void;
}

const useHistoryStore = create<HistoryState>((set, get) => ({
  past: [],
  present: initialSnapshot,
  future: [],
  pushState: (snapshot) =>
    set({
      past: [...get().past, get().present],
      present: snapshot,
      future: [], // clear redo stack on new action
    }),
  undo: () => {
    const { past, present } = get();
    if (past.length === 0) return;
    set({
      past: past.slice(0, -1),
      present: past[past.length - 1],
      future: [present, ...get().future],
    });
  },
  redo: () => {
    const { future, present } = get();
    if (future.length === 0) return;
    set({
      past: [...get().past, present],
      present: future[0],
      future: future.slice(1),
    });
  },
}));

In that example, a CanvasSnapshot must be an immutable copy of the state you intend to restore. Group drag events into meaningful edits if positions belong in history. Neither a version array nor a toolbar button proves that every gesture is captured; test each supported edit.

It's the least glamorous code in the product, in the same category as the ⌘K command palette: nobody praises it, everybody notices its absence.

Unnecessary re-renders are one common bottleneck, alongside expensive node markup, many edges, and complex styling. React Flow's performance guidance recommends stable components, callbacks, and narrow subscriptions. Profile the interaction before deciding which cost dominates your canvas.

Memoize custom nodes. Keep node components and the nodeTypes object stable. Start with React.memo; only add a custom comparator when profiling justifies it, and compare every prop that affects rendering or behavior.

Batch state updates. When the AI generates a 30-node diagram, I don't add nodes one at a time, which would trigger 30 re-renders. I set the entire node array in one setState call.

Lazy load the canvas. React Flow isn't a tiny dependency, so I dynamically import it and keep it off the initial page load for users who land on the marketing page. That discipline matters more once the app is installed as a PWA and opened cold, where there's no browser chrome to hide a slow start behind.

Measure representative graphs. Compare drag, zoom, selection, and editing on a low-end device as well as your development machine. Offscreen rendering can be configured, but should not be described as automatic virtualization without checking the actual setting. Node count alone is not a benchmark.

The best way to understand the canvas is to use it. Open Architecture in Codelit, describe a system, and inspect the result. Drag nodes around. Click edges. Try the minimap. Or start from a pre-built template and modify it.

If you're building your own node-based UI with React Flow, I hope this saves you some of the trial and error I went through. The library removes a large amount of editor plumbing. The product work remains yours: preserve intent, make edits reversible, and keep a dense diagram understandable. Those are the details people feel every time they use it.