Computational Framework

The Computational Framework is an interactive node-based editor designed for composing complex mathematical operations into visual computation graphs. Built with Next.js 15, TypeScript, Tailwind CSS, and shadcn/ui, it runs entirely in the browser with a server-side AI generation proxy.

This project was built specifically to demonstrate that a modulo 2 ring inherently allows for boolean operations, serving as a powerful mathematical proof that an entire computer architecture can effectively be built up from these foundational modular arithmetic principles.

Key Features

• Visual Node Editor: Drag-and-drop canvas with infinite panning (middle-click or alt+drag) and zoom (Ctrl+scroll). A minimap provides a birds-eye view of large graphs.
• Arithmetic Formulas: Each node evaluates any mathjs expression — a + b, floor(sqrt(q)), etc. Standard inputs by name, plus q/Q to reference the node’s own previous value for feedback loops.
• Per-Node Modular Arithmetic: Toggle modulo reduction per node with a configurable base (defaulting to mod 2 for boolean logic demonstrations). Under mod 2, + acts as XOR and * acts as AND.
• Cyclic Graphs: Feedback loops are fully supported through the q variable, allowing nodes to reference their own previous states for continuous sequential logic — enabling D flip-flops, latches, and state machines.
• AI-Assisted Generation: Describe a computation in plain English and GPT-4, Gemini, or DeepSeek generates the node graph. API keys are proxied server-side through Next.js API routes, never exposed to the browser.
• Undo/Redo: Full undo/redo stack (Ctrl+Z / Ctrl+Shift+Z) with a 50-snapshot history.
• Animated Connections: Wires dynamically animate with arrowheads to show the exact flow direction of computations between nodes.
• Logger Nodes: Clock-triggered input loggers record values on every rising edge, essential for debugging sequential circuits.

Architecture

src/
├── app/
│   ├── page.tsx                    ← root page (ErrorBoundary wrapper)
│   └── api/ai/route.ts             ← server-side AI proxy
├── components/computational-framework/
│   ├── ComputationalFramework.tsx   ← canvas + hook composition (~225 LOC)
│   ├── ComputationalNode.tsx        ← thin wrapper around BaseNode
│   ├── BaseNode.tsx                 ← shared node card (header, inputs, drag)
│   ├── LoggerNode.tsx               ← clock-triggered logger
│   ├── AIHelper.tsx                 ← AI generation modal
│   ├── NodePalette.tsx              ← node type picker sidebar
│   ├── ShortcutsPanel.tsx           ← keyboard shortcuts reference
│   ├── Minimap.tsx                  ← birds-eye canvas view
│   └── SettingsPanel.tsx            ← framework settings sheet
├── hooks/
│   ├── useNodes.ts                  ← node state, CRUD, evaluation
│   ├── useConnections.ts            ← connection state & CRUD
│   ├── useCanvas.ts                 ← pan, zoom, drag, selection
│   ├── useKeyboard.ts               ← keyboard shortcuts
│   └── useUndoRedo.ts               ← undo/redo snapshot stack
└── lib/
    ├── evaluationEngine.ts          ← pure evaluation logic (testable)
    ├── nodeRegistry.ts              ← node type descriptors
    └── demoGraph.ts                 ← first-visit half-adder demo

The architecture is highly decoupled: the evaluationEngine is pure logic with zero React dependency and is covered by 26 Vitest unit tests. Canvas interactions (pan, zoom, drag-to-select, marquee selection) are isolated in useCanvas. State management uses plain React hooks with no external state library.

How Evaluation Works

Each time a node receives updated inputs, the evaluation engine:

1. Topologically sorts all connected nodes.
2. Evaluates each node’s mathjs expression with the current input values in scope (node labels as variable names, plus q for the node’s own previous value).
3. Handles cyclic graphs by feeding the previous tick’s q value into the current evaluation.
4. Pushes the result through the mod reduction filter if enabled.

Demo Graph

On first visit, a half-adder circuit loads automatically — two XOR gates (sum) and an AND gate (carry) wired together under mod 2, demonstrating how boolean logic emerges naturally from modular arithmetic.

The Computational Framework makes the mathematical foundations of computer architecture tangible. It bridges discrete mathematics and physical hardware implementation through interactive visualisation.