Architecture

Architecture

This page is for contributors. It explains the tech stack, how the code is organised, and the core design idea that keeps AutomataLab fast and testable.

Tech stack

Layer	Technology
Desktop shell	Tauri v2 (Rust) — native windows, file dialogs, auto‑updater
UI	React 19 + TypeScript
Build / dev	Vite 6
State	Zustand stores
Graph canvas	React Flow (@xyflow/react)
Auto‑layout	ELK (elkjs)
Animation	Framer Motion
Styling	Tailwind CSS v4
Tests	Vitest

Core design: a pure, decoupled engine

The single most important principle is that the simulation engine is pure TypeScript with no dependency on React, the DOM, or Tauri. This buys three things:

1. Testability — engines are unit‑tested directly (the suite has 200+ tests).
2. A web build — because nothing in the engine needs Tauri, the same code ships as a Vercel web app. Tauri plugins are dynamically imported so the web bundle never pulls in native‑only code.
3. Reuse — the interactive simulator, the batch runner, and the exporters all run the same engine via a headless run‑to‑completion path, so results never diverge.

Directory map

src/
  engines/
    core/            # shared types, computation‑tree builder, helpers, engineFactory
    dfa/ nfa/ enfa/  # finite‑automaton engines (+ *.test.ts)
    dpda/ npda/      # pushdown engines
    tm/ lba/         # Turing‑machine & linear‑bounded engines
  store/             # Zustand: machineStore, simulationStore, uiStore
  hooks/             # useSimulation — bridges stores ↔ engine
  components/
    canvas/          # AutomataCanvas, StateNode, TransitionEdge, ContextMenu, TransitionEditor
    panels/          # SidePanel, ValidationPanel, HistoryLog, ComputationTreePanel, TapePanel, DeltaTablePanel
    controls/        # SimulationControls, InputBar, BatchRunnerModal
    toolbar/         # Toolbar, FileControls
    layout/          # HelpModal, ExportModal
  utils/             # validator, fileManager, exporters, batch
  index.css          # global styles / theme tokens
src-tauri/           # Rust shell + tauri.conf.json
.github/workflows/   # release.yml (tagged builds + release), deploy.yml (Pages)

How the pieces fit

• engines/core/types.ts defines the shared machine/automaton types and the configuration shape each engine steps through.
• engines/core/engineFactory.ts creates the right engine for a machine type and provides a runToCompletion helper used by the batch runner and exporters.
• Each engine (e.g. engines/tm/TMEngine.ts) implements stepping/branching for its model.
• engines/core/computationTree.ts turns a run into the tree/trellis the UI renders (merging configurations for FA, branching for NPDA).
• Stores (Zustand): machineStore holds the machine definition and edit history (undo/redo); simulationStore holds run state; uiStore holds panel/tab/focus UI state.
• hooks/useSimulation.ts is the bridge: it watches a structural signature of the machine and auto‑resets the simulation to Idle whenever the structure changes, which is what keeps a finished run from "locking" the editor.
• utils/: validator produces the Validation‑tab items; fileManager serialises/parses .autolab.json (Tauri dialogs on desktop, download/upload on web); exporters produce CSV/LaTeX/JSON; batch parses test cases and runs them headlessly.

Adding a new machine type (sketch)

1. Add the type to engines/core/types.ts.
2. Implement an engine under engines/<type>/ with its own *.test.ts.
3. Register it in engineFactory.
4. Teach the validator, transition editor, δ‑table, and fileManager about its transition shape.
5. Wire any model‑specific panel (e.g. tape/stack) and toolbar settings.
6. Add tests and run npm test.

Continuous integration

• Vercel deployment — web deployments are handled via Vercel for the live simulator.
• release.yml — on a pushed v* tag, builds signed installers for Windows/macOS/Linux via tauri-action, then publishes a GitHub Release whose notes are extracted from the top section of CHANGELOG.md. A follow‑up job mirrors the updater manifest to updater.json for the auto‑updater.

See CONTRIBUTING.md for contribution guidelines.