# strilanc/quirk architecture

> Architecture diagram of the GitHub repository strilanc/quirk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strilanc/quirk
- Repository: https://github.com/strilanc/quirk

## Overview

##### Project type and purpose
- Quirk is a single-page, in-browser quantum circuit simulator. There is no separate backend server—the entire system runs as static HTML/JS/CSS, built and tested via Node/Grunt and deployed as a self-contained web app.
- Its purpose is to let users drag-and-drop quantum gates onto a canvas and instantly see simulation results. Key features include real-time animation, inline state displays, bookmarkable circuits, and support for up to 16 qubits.

##### File structure
- Top-level build/configuration:
- GruntFile.js – build & bundling tasks
- package.json, npm scripts – dependency management, test runner, build pipeline
- .github/workflows/ci.yml – CI integration (Travis/GitHub Actions)
- PuppeteerRunTests.js, PuppeteerScreenshotCircuit.js – headless‐browser test automation
- Core application code under src/:
- src/base – shared utilities (throttling, RNG, error handling, formatting)
- src/math – linear algebra & complex-number support (Matrix, Complex, FormulaParser)
- src/circuit – simulation engine (CircuitDefinition, EvalContext, Serializer, stats)
- src/gates – gate definitions and display-only gates (FourierTransformGates, MeasurementGate, BlochSphereDisplay, etc.)
- src/ui – user-interaction layer (drag/drop, toolbox, menu, URL routing, undo/redo)
- src/browser – cross-browser glue (clipboard, history, touch blocking, file saving)
- src/main.js – entry point that wires UI ↔ simulation ↔ renderer
- Tests under test/ and performance tests under test_perf/ use Karma and Puppeteer.

##### README for insights
- Confirms it’s a pure-client SPA with no server component.
- Describes build steps: python/npm → test → build → output to out/quirk.html.

a. Main components
- Build & CI System (Node/npm, Grunt, Karma, Puppeteer, GitHub CI)
- Static Web App Host (serves out/quirk.html + assets)
- Browser Runtime
– UI Layer (src/ui + src/browser)
– Simulation Engine (src/circuit + src/base + src/math)
– Gate Library (src/gates)
– Rendering Layer
· WebGL Renderer (src/webgl)
– State & Serialization (URL bookmark, Serializer)
b. Relationships & interactions
- UI dispatches user events → Simulation Engine evaluates circuit → Engine emits qubit states → Rendering Layer paints canvas/updates WebGL displays → UI updates inspector panels + URL state.
- Build & CI kicks off unit tests and performance tests, then bundles src/ into a single HTML+JS.
c. Architectural patterns & principles
- Single Responsibility: each subfolder has a well-defined role.
- Dependency injection via Config.js and EvalContext.
d. Key technologies/frameworks
- Node.js, npm, Grunt for build
- Karma and Puppeteer for testing
- WebGL for GPU-accelerated rendering
- HTML partials (handlebars-style templates) for error/export dialogs
- Vanilla JS modules, no frontend framework

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI System
    subgraph "Build & CI System"
        Grunt["GruntFile.js"]:::build
        Package["package.json"]:::build
        CI[".github/workflows/ci.yml"]:::build
        KarmaUnit["karma.test.conf.js"]:::build
        KarmaPerf["karma.test_perf.conf.js"]:::build
        PuppeteerRun["PuppeteerRunTests.js"]:::build
        PuppeteerShot["PuppeteerScreenshotCircuit.js"]:::build
    end
    Grunt -->|builds| Artifact["Deployment Artifact\n(out/quirk.html + assets)"]:::build
    Package --> Artifact
    CI --> Artifact
    KarmaUnit --> Artifact
    KarmaPerf --> Artifact
    PuppeteerRun --> Artifact
    PuppeteerShot --> Artifact

    %% Static Host
    Artifact --> StaticHost["Static Web App Host"]:::external
    subgraph "Static Web App Host"
        HTMLTemplate["quirk.template.html"]:::build
        ErrorPartial["error.partial.html"]:::build
        ExportPartial["export.partial.html"]:::build
        ForgePartial["forge.partial.html"]:::build
        MenuPartial["menu.partial.html"]:::build
    end
    StaticHost --> Browser["Browser Runtime"]:::external

    %% Browser Runtime
    Browser --> Entry["Entry Point\nsrc/main.js"]:::ui

    subgraph "Browser Runtime"
        Entry
        subgraph "UI & Integration"
            UIFolder["src/ui"]:::ui
            BrowserGlue["src/browser"]:::ui
        end
        subgraph "Simulation Engine"
            CircuitFolder["src/circuit"]:::core
            BaseFolder["src/base"]:::core
            MathFolder["src/math"]:::core
        end
        GateFolder["src/gates"]:::core
        subgraph "Rendering Layer"
            CanvasFolder["src/draw"]:::render
            WebGLFolder["src/webgl"]:::render
        end
        subgraph "State & Serialization"
            Serializer["src/circuit/Serializer.js"]:::ui
            Url["src/ui/url.js"]:::ui
            History["src/browser/HistoryPusher.js"]:::ui
        end
    end

    %% User Interaction Flow
    User["User"]:::external
    User -->|"interacts"| UIFolder
    UIFolder -->|"dispatch events"| CircuitFolder
    CircuitFolder -->|"qubit states"| CanvasFolder
    CircuitFolder -->|"qubit states"| WebGLFolder
    CanvasFolder -->|"render output"| UIFolder
    WebGLFolder -->|"render output"| UIFolder
    GateFolder --> CircuitFolder
    GateFolder --> UIFolder
    UIFolder --> Url
    Url --> History
    History --> Serializer
    Serializer --> UIFolder

    %% Build Styles
    classDef build fill:#dddddd,stroke:#999999,color:#333333
    classDef external fill:#eeeeff,stroke:#8888ff,color:#000088
    classDef core fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef render fill:#ccffcc,stroke:#33cc33,color:#006600
    classDef ui fill:#ffe5cc,stroke:#ff9933,color:#663300

    %% Click Events
    click Grunt "https://github.com/strilanc/quirk/blob/master/GruntFile.js"
    click Package "https://github.com/strilanc/quirk/blob/master/package.json"
    click CI "https://github.com/strilanc/quirk/blob/master/.github/workflows/ci.yml"
    click KarmaUnit "https://github.com/strilanc/quirk/blob/master/karma.test.conf.js"
    click KarmaPerf "https://github.com/strilanc/quirk/blob/master/karma.test_perf.conf.js"
    click PuppeteerRun "https://github.com/strilanc/quirk/blob/master/PuppeteerRunTests.js"
    click PuppeteerShot "https://github.com/strilanc/quirk/blob/master/PuppeteerScreenshotCircuit.js"
    click HTMLTemplate "https://github.com/strilanc/quirk/blob/master/html/quirk.template.html"
    click ErrorPartial "https://github.com/strilanc/quirk/blob/master/html/error.partial.html"
    click ExportPartial "https://github.com/strilanc/quirk/blob/master/html/export.partial.html"
    click ForgePartial "https://github.com/strilanc/quirk/blob/master/html/forge.partial.html"
    click MenuPartial "https://github.com/strilanc/quirk/blob/master/html/menu.partial.html"
    click Entry "https://github.com/strilanc/quirk/blob/master/src/main.js"
    click UIFolder "https://github.com/strilanc/quirk/tree/master/src/ui"
    click BrowserGlue "https://github.com/strilanc/quirk/tree/master/src/browser"
    click CircuitFolder "https://github.com/strilanc/quirk/tree/master/src/circuit"
    click BaseFolder "https://github.com/strilanc/quirk/tree/master/src/base"
    click MathFolder "https://github.com/strilanc/quirk/tree/master/src/math"
    click GateFolder "https://github.com/strilanc/quirk/tree/master/src/gates"
    click CanvasFolder "https://github.com/strilanc/quirk/tree/master/src/draw"
    click WebGLFolder "https://github.com/strilanc/quirk/tree/master/src/webgl"
    click Serializer "https://github.com/strilanc/quirk/blob/master/src/circuit/Serializer.js"
    click Url "https://github.com/strilanc/quirk/blob/master/src/ui/url.js"
    click History "https://github.com/strilanc/quirk/blob/master/src/browser/HistoryPusher.js"
```
