# hausen/circuit-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/hausen/circuit-simulator
- Repository: https://github.com/hausen/circuit-simulator

## Overview

##### Project Type and Purpose
- This is a standalone Java circuit-simulator (also usable as a browser applet) based on Paul Falstad’s original work, extended with import/export, file saving, bundled circuit examples, and UI improvements.
- It is not a web service or microservice – it is a desktop/applet GUI application that simulates electrical circuits in real time.

##### File Structure Analysis
- Top-level:
- README.md, .gitignore, src/Makefile, Manifest.txt – build and metadata
- src/*.java – core Java sources
- src/circuits/*.txt – sample circuit definitions bundled as resources
- Key source packages/areas:
- Core engine: Circuit.java, CircuitElm.java and its ∼70 subclasses (ResistorElm, CapacitorElm, GateElm, etc.), CircuitNode/Link, CircuitLayout
- Simulation loop & orchestration: CirSim.java, CircuitCanvas.java, Scope.java
- UI/Controller: EditDialog*.java, ImportExport*.java, EditOptions, ImportExportDialogFactory
- Persistence/Resources: dump format (text), circuits/*.txt, importCircuit/exportCircuit hooks for applet integration

##### Architectural Patterns & Design Principles
- Polymorphism/Factory: each circuit element is a subclass of CircuitElm, selected and instantiated dynamically
- MVC-like separation:
- Model = Circuit, CircuitElm hierarchy, CircuitNode/Link, CircuitLayout
- View = CircuitCanvas (renders the model), Scope (oscilloscope view)
- Controller = CirSim main class, EditDialog*/ImportExportDialog* classes, UI event handlers
- Resource-bundling: circuits/*.txt loaded at startup into the “Circuit” menu

##### Main Components
a. Java Runtime Environment
b. Application Entrypoints
- CirSim (main for desktop JAR)
- Circuit (applet)
c. Simulation Engine (Model)
- Circuit (circuit state & node graph)
- CircuitElm subclasses (components)
- CircuitNode, CircuitNodeLink, CircuitLayout
d. Presentation Layer (View & Controller)
- CircuitCanvas (rendering engine)
- Scope (real-time waveform display)
- EditDialog*/EditInfo/EditOptions (component editing UI)
- ImportExportDialog*/Factory (load/save dialogs)
e. Persistence & Resources
- circuits/*.txt (bundled circuit definitions)
- exportCircuit / importCircuit JavaScript hooks (applet mode)
- File system (application mode)
f. Build & Packaging
- Makefile, javac, jar with Manifest.txt

##### Relationships and Data Flows
- User interacts with UI components (CircuitCanvas, dialogs) → Controller (CirSim, EditDialog*, ImportExportDialog*)
- Controller invokes Simulation Engine APIs (Circuit.addNode, CircuitElm.step, etc.)
- Simulation Engine updates circuit state → View components (CircuitCanvas.redraw(), Scope.update())
- Persistence module reads/writes text dumps:
- On load: ImportExportDialog → Parser → Circuit & CircuitElm instances
- On save: Circuit.dump() → Exporter → file or JavaScript callback
- Resource loader at startup scans circuits/*.txt → registers menu entries → clicking loads via same import path

##### Important Details to Capture
- The polymorphic factory pattern for element instantiation
- The MVC-style interaction and data-flow separation
- Dual operation modes: desktop (file system) vs. applet (JavaScript hooks)
- Bundled circuit resources and how they plug into the import pipeline
- Real-time rendering (CircuitCanvas) vs. snapshot export (dump format)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Java Runtime Environment"
        JRE["Java Runtime Environment"]:::platform
    end

    subgraph "Application Entrypoints"
        Main["CirSim (Desktop Main)"]:::entry
        Applet["Circuit (Applet Entry)"]:::entry
    end

    subgraph "Presentation Layer"
        Canvas["CircuitCanvas"]:::ui
        Scope["Scope"]:::ui
        subgraph "Edit Dialogs"
            EditDlgAll["EditDialog*, EditInfo, EditOptions"]:::ui
        end
        subgraph "Import/Export Dialogs"
            ImpExpAll["ImportExportDialog*, Factory, Layout"]:::ui
        end
    end

    subgraph "Simulation Engine (Model)"
        Circuit["Circuit"]:::engine
        ElmBase["CircuitElm Base Class"]:::engine
        ElmSubs["CircuitElm Subclasses"]:::engine
        NodeGraph["CircuitNode / CircuitNodeLink"]:::engine
        Layout["CircuitLayout"]:::engine
    end

    subgraph "Persistence & Resources"
        Resources["circuits/*.txt"]:::data
        JSHooks["Applet JS Hooks"]:::data
        FS["File System"]:::data
    end

    subgraph "Build & Packaging"
        Makefile["Makefile"]:::build
        Manifest["Manifest.txt"]:::build
    end

    %% Relationships
    JRE --> Main
    JRE --> Applet

    Main --> Canvas
    Main --> Scope
    Main --> EditDlgAll
    Main --> ImpExpAll
    Applet --> Canvas
    Applet --> Scope
    Applet --> EditDlgAll
    Applet --> ImpExpAll

    Canvas --> Circuit
    Scope --> Circuit
    EditDlgAll --> Circuit
    ImpExpAll --> Circuit

    Circuit --> ElmBase
    ElmBase --> ElmSubs
    Circuit --> NodeGraph
    Circuit --> Layout

    ImpExpAll --> Resources
    Resources --> Circuit

    Circuit --> FS
    Circuit --> JSHooks

    Main --> Resources
    Resources --> ImpExpAll

    Makefile --> Main
    Makefile --> Applet
    Manifest --> Main
    Manifest --> Applet

    %% Click Events
    click Main "https://github.com/hausen/circuit-simulator/blob/master/src/CirSim.java"
    click Applet "https://github.com/hausen/circuit-simulator/blob/master/src/Circuit.java"
    click Circuit "https://github.com/hausen/circuit-simulator/blob/master/src/Circuit.java"
    click ElmBase "https://github.com/hausen/circuit-simulator/blob/master/src/CircuitElm.java"
    click ElmSubs "https://github.com/hausen/circuit-simulator/blob/master/src/ResistorElm.java"
    click NodeGraph "https://github.com/hausen/circuit-simulator/blob/master/src/CircuitNode.java"
    click NodeGraph "https://github.com/hausen/circuit-simulator/blob/master/src/CircuitNodeLink.java"
    click Layout "https://github.com/hausen/circuit-simulator/blob/master/src/CircuitLayout.java"
    click Canvas "https://github.com/hausen/circuit-simulator/blob/master/src/CircuitCanvas.java"
    click Scope "https://github.com/hausen/circuit-simulator/blob/master/src/Scope.java"
    click EditDlgAll "https://github.com/hausen/circuit-simulator/blob/master/src/EditDialog.java"
    click EditDlgAll "https://github.com/hausen/circuit-simulator/blob/master/src/EditDialogLayout.java"
    click EditDlgAll "https://github.com/hausen/circuit-simulator/blob/master/src/EditInfo.java"
    click EditDlgAll "https://github.com/hausen/circuit-simulator/blob/master/src/EditOptions.java"
    click ImpExpAll "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportDialog.java"
    click ImpExpAll "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportAppletDialog.java"
    click ImpExpAll "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportClipboardDialog.java"
    click ImpExpAll "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportFileDialog.java"
    click ImpExpAll "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportDialogFactory.java"
    click ImpExpAll "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportDialogLayout.java"
    click Resources "https://github.com/hausen/circuit-simulator/tree/master/src/circuits/"
    click JSHooks "https://github.com/hausen/circuit-simulator/blob/master/src/ImportExportAppletDialog.java"
    click Makefile "https://github.com/hausen/circuit-simulator/tree/master/src/Makefile"
    click Manifest "https://github.com/hausen/circuit-simulator/blob/master/src/Manifest.txt"

    %% Styles
    classDef platform fill:#eef,stroke:#77f,stroke-width:1px
    classDef entry fill:#ffd,stroke:#fa0,stroke-width:1px
    classDef ui fill:#dfd,stroke:#0a0,stroke-width:1px
    classDef engine fill:#ddf,stroke:#00f,stroke-width:1px
    classDef data fill:#ffb,stroke:#fa0,stroke-width:1px
    classDef build fill:#ccc,stroke:#888,stroke-width:1px
```
