# tscircuit/runframe architecture

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

- Interactive diagram: https://gitdiagram.com/tscircuit/runframe
- Repository: https://github.com/tscircuit/runframe

## Overview

##### Main Components
- User Interface Components – These include the individual React components housed under lib/components (for example, RunFrame, CircuitJsonPreview, RunFrameWithApi, RunFrameForCli, and UI primitives such as buttons, checkbox, inputs, etc.). They provide the core functionality of displaying the circuit’s PCB, schematic, bill of materials, and error information.
- File Server / Edit Event System – In the “Development” section, an edit events sequence is described that involves a File Server, Browser RunFrame, and Viewer elements working together with event handling. This component manages fetching and updating manual edits (using API endpoints) and the overall integration of change events.
- External Integrations – Highlight the integration points for optional features (import/export features, JLC PCB API integrations, etc.) located in lib/optional-features. Also include the standalone iframe integration that allows embedding the RunFrame into external host pages.

##### Relationships and Interactions
- Optional APIs (e.g., for snippet management and import/export flows) that interact either with the RunFrame components or externally hosted services.

##### Architectural Patterns and Design Principles
- Component-Based Design – Emphasize the modular design inherent to React, where separate components (e.g., RunFrame, CircuitJsonPreview) are loosely coupled with clear responsibilities.
- Separation of Concerns – Differentiate logical layers: the UI components, the worker thread (which handles computation and code transformation), and the event bus for synchronization with file-server events.

##### Relevant Technologies, Frameworks, and Libraries
- React – The project is built as a collection of React components.
- Web Workers – Employed to offload tscircuit execution and Babel transformations.
- Babel – Used for transpiling TypeScript to JavaScript.
- TypeScript – Underlies the entire code base.
- Optional integrations – Libraries or APIs for handling file import/export, snippet saving, and synchronization with the JLCPCB API are present.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Components"
        UF1["RunFrame Component"]:::ui
        UF2["CircuitJsonPreview Component"]:::ui
        UF3["RunFrameWithApi Component"]:::ui
        UF4["RunFrameForCli Component"]:::ui
        UIF["UI Primitives"]:::ui
    end

    subgraph "Web Worker & Code Transpilation"
        WW["Web Worker (tscircuit+Babel)"]:::worker
        RSC["Render to Circuit JSON"]:::worker
    end

    subgraph "File Server / Edit Event System"
        FS["File Server (Edit Events)"]:::event
        EEC["Edit Event Controller"]:::event
        EB["Event Bus"]:::event
    end

    subgraph "External Integrations"
        IC["Import Component Dialog"]:::external
        EX["Exporting Features"]:::external
        IM["Importing Features"]:::external
    end

    %% UI to Web Worker interaction
    UF1 -->|"tscircuit_execution"| WW
    WW -->|"processing_result"| UF2
    WW -->|"uses"| RSC

    %% Edit Event flow
    UF1 -->|"edit_events"| FS
    FS -->|"manual_edits"| EEC
    EEC -->|"update_event"| UF2
    FS ---|"event_sync"| EB
    EB ---|"broadcast"| UF1

    %% Optional External Integrations from UI
    UF3 ---|"optional_integration"| IC
    UF3 ---|"optional_integration"| EX
    UF3 ---|"optional_integration"| IM

    %% Styles
    classDef ui fill:#AED6F1,stroke:#2E86C1,stroke-width:2px,rx:5,ry:5;
    classDef worker fill:#ABEBC6,stroke:#239B56,stroke-width:2px,rx:5,ry:5;
    classDef event fill:#F9E79F,stroke:#F1C40F,stroke-width:2px,rx:5,ry:5;
    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,rx:5,ry:5;

click UF1 "https://github.com/tscircuit/runframe/blob/main/lib/components/RunFrame/RunFrame.tsx"
click UF2 "https://github.com/tscircuit/runframe/blob/main/lib/components/CircuitJsonPreview/CircuitJsonPreview.tsx"
click UF3 "https://github.com/tscircuit/runframe/blob/main/lib/components/RunFrameWithApi/RunFrameWithApi.tsx"
click UF4 "https://github.com/tscircuit/runframe/blob/main/lib/components/RunFrameForCli/RunFrameForCli.tsx"
click UIF "https://github.com/tscircuit/runframe/tree/main/lib/components/ui/"
click WW "https://github.com/tscircuit/runframe/blob/main/lib/runner.ts"
click RSC "https://github.com/tscircuit/runframe/blob/main/lib/dev/render-to-circuit-json.ts"
click FS "https://github.com/tscircuit/runframe/blob/main/lib/utils/pcbManualEditEventHandler.ts"
click EEC "https://github.com/tscircuit/runframe/blob/main/lib/hooks/use-edit-event-controller.ts"
click IC "https://github.com/tscircuit/runframe/tree/main/lib/components/ImportComponentDialog/"
click EX "https://github.com/tscircuit/runframe/tree/main/lib/optional-features/exporting/"
click IM "https://github.com/tscircuit/runframe/tree/main/lib/optional-features/importing/"
```
