ARCHITECTURE.md

Architecture

This document summarizes how the Interactive Reversible Debugger (IRD) is structured and how execution and reversal work at a high level.

High-level diagram

flowchart TB
  subgraph ui [React UI]
    Index[Index page]
    Panels[ControlPanel StateViewer Graphs Quantum]
    Index --> Panels
  end

  subgraph exec [Execution]
    Backend[ExecutionBackend]
    Engine[executionEngine executeCode]
    SafeExpr[safeExpression]
    Backend --> Engine
    Engine --> SafeExpr
  end

  subgraph data [Persistence optional]
    Supa[Supabase client]
    DebugSvc[debuggerService]
    Supa --> DebugSvc
  end

  Index --> Backend
  Index --> DebugSvc

Loading

Frontend application

• Entry: src/main.tsx, src/App.tsx.
• Routing: React Router — protected / (debugger), public /project and /login.
• State / server cache: TanStack Query with defaults in App.tsx; devtools enabled in development only.
• Auth: src/contexts/AuthContext.tsx uses the Supabase client from src/integrations/supabase/client.ts.

Execution pipeline

1. ExecutionBackend (src/lib/executionBackend.ts)
   Abstraction over “run this source and emit states.” The default implementation delegates to executeCode.

2. executeCode (src/lib/executionEngine.ts)
   Line-oriented simulation: walks source lines, maintains a simple call stack model, emits ExecutionState snapshots (variables, line, object graph, memory estimate).

   Options include:

   • targetLine — stop after a bounded forward run (used for stepping).
   • signal — AbortSignal to cancel long runs (e.g. when leaving the page or stopping playback).
   • stepDelayMs — delay between steps (wired to the UI “execution speed” slider).

3. Numeric expressions
   Assignment right-hand sides that look like pure arithmetic are evaluated with evaluateSafeNumericExpression. There is no general JavaScript interpreter in the browser build.

4. Reversal in the UI
   “Step back” navigates within the already recorded ExecutionState[] array. True instruction-level reverse execution is not implemented; see Reversible execution model.

Object graph and visualization

• src/lib/objectRelationshipAnalyzer.ts derives relationships from variable snapshots.
• src/lib/quantumExecutionEngine.ts and related UI drive the quantum educational simulator (not a full QC backend).

Sandboxed numeric evaluation (optional path)

• Worker: src/workers/sandbox.worker.ts
• Client: src/lib/sandboxRunner.ts (evaluateInSandbox)
  The worker only runs the same safe numeric parser; it exists to keep evaluation off the main thread when you choose to wire it in.

Reversible execution model

Helpers in src/lib/reversibleExecutionModel.ts describe an immutable snapshot timeline. The product’s current user-visible reversal is snapshot replay (index into history), aligned with “event sourcing lite”: forward execution appends states; backward moves the cursor without re-running the engine backward.

A future milestone would add explicit inverse operations or bytecode with guaranteed semantic reverse (memory vs fidelity tradeoff).

Configuration

• Vite: vite.config.ts (path alias @ → src).
• TypeScript: tsconfig.app.json (strict app code), tsconfig.node.json for config files.
• Env validation: src/lib/env.ts (Zod).

Related reading

• SUPABASE.md — database tables and RLS expectations.