# seleniumhq/selenium-ide architecture

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

- Interactive diagram: https://gitdiagram.com/seleniumhq/selenium-ide
- Repository: https://github.com/seleniumhq/selenium-ide

## Overview

##### Project Type and Purpose
- This is a large monorepo for an open-source automation tool: Selenium IDE.
- It comprises a desktop Electron application (with React UI), multiple CLIs, a playback engine, code-export tooling, migration and test utilities, all wired together via shared libraries in a pnpm/Bazel workspace.

##### High-Level Architectural Overview
- Monorepo root: orchestration via pnpm-workspace.yaml and BUILD.bazel.
- Packages:
- selenium-ide – Electron app (Main & Renderer processes, React frontend).
- side-runner, side-cli – NodeJS CLIs for batch execution and interactive use.
- side-runtime – Playback engine interpreting .side test files.
- side-api – Typed IPC façade for renderer↔main communication and plugins.
- side-model – Metadata definitions (commands, args, I18N).
- side-commons – Shared utilities.
- side-code-export + code-export-* – Transpilers to various target languages.
- side-migrate – Legacy test-file migration tool.
- side-testkit & webdriver-testkit – Fixtures and helpers for testing.
- get-driver – WebDriver binary management.

##### Main Components & Interactions
A. Electron Application (“selenium-ide” package)
1. Main Process
– Initializes the app, spawns BrowserWindow instances for UI and playback.
– Hosts “session controllers” implementing side-api commands (Driver, Playback, Menu, Plugins, File I/O, etc.)
– Manages Electron IPC channels (utilizing side-api types)
2. Renderer Process (React UI)
– UI components (AppBar, Controls, Drawer, Project Editor, Playback Panels)
– Uses side-api client to send commands (record, playback, open/close windows).
– Loads preload scripts into UI windows for recording/playback.
3. Preload Scripts
– Injected into each BrowserWindow to bridge DOM events → IPC commands (recorders, selectors).

B. NodeJS Tools
– side-runner: Loads .side files, invokes side-runtime playback API (direct library calls), reports results.
– side-cli: Interactive TTY UI (Ink/React), drives side-runtime like side-runner.
– side-migrate: Reads legacy IDE HTML, outputs .side JSON via migration pipeline modules.
– side-code-export & code-export-*: Library pipeline to transpile .side JSON → language code.

C. Shared Libraries
– side-runtime: Core engine (command tree, callstack, errors, webdriver sync)
– side-api: Type definitions and boilerplate for IPC; shared by all packages needing IDE commands.
– side-model: Schema of commands & args (used by UI, code-export, autocomplete).
– side-commons: Utility functions (events, async, string).
– get-driver & webdriver-testkit: Download, resolve, cache WebDriver binaries for playback.

D. External Integrations
– Web browsers (Chrome, Firefox) via WebDriver
– File system (open/save projects, load code-export templates)
– Plugins (external node modules hooking into side-api)
– CI/CD (GitHub Actions, Bazel)

##### Architectural Patterns & Principles
- Monorepo modularization: each feature/tool lives in its own package, dependencies declared in package.json and BUILD.bazel.
- Electron multi-process: clear separation of Main vs Renderer, bridged by IPC.
- Layered playback engine: model → runtime → executor (WebDriver)
- Pluggable commands and code-export via well-defined side-api interfaces
- Shared type definitions (TypeScript) to enforce consistency across packages

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Application
    subgraph "Electron App"
      direction TB
      Launcher["launcher: bin.js"]:::electron
      WebpackCfg["webpack.config.ts"]:::electron
      Main["Main Process"]:::electron
      Renderer["Renderer Process (React UI)"]:::electron
      Preload["Preload Scripts"]:::electron
    end

    %% NodeJS Tools
    subgraph "NodeJS Tools"
      direction TB
      RunnerApp["side-runner"]:::cli
      RunnerBin["bin.ts"]:::cli
      RunnerRun["run.ts"]:::cli
      CLIApp["side-cli"]:::cli
      CLIIndex["index.tsx"]:::cli
      CLIComp["components"]:::cli
    end

    %% Shared Libraries: Runtime & API & Model & Commons & DriverMgr
    subgraph "Shared Libraries"
      direction TB
      subgraph "side-runtime"
        RIndex["index.ts"]:::shared
        RPlayback["playback.ts"]:::shared
        RTree["playback-tree"]:::shared
        RWebdriver["webdriver.ts"]:::shared
      end
      subgraph "side-api"
        APIIndex["index.ts"]:::shared
        APICommands["commands"]:::shared
        APIClasses["classes"]:::shared
        APIModels["models"]:::shared
      end
      subgraph "side-model"
        ModelCommands["Commands.ts"]:::shared
        ModelArgTypes["ArgTypes.ts"]:::shared
        ModelI18N["I18N"]:::shared
      end
      subgraph "side-commons"
        CommAsync["async.ts"]:::shared
        CommEvents["events.ts"]:::shared
        CommString["string.ts"]:::shared
      end
      subgraph "get-driver"
        GDownload["download-driver.ts"]:::shared
        GResolve["resolve-driver.ts"]:::shared
      end
    end

    %% Code Export Pipeline
    subgraph "Code Export Pipeline"
      direction TB
      CEIndex["side-code-export/index.ts"]:::export
      CECores["side-code-export/code-export"]:::export
      LanguageMod["code-export-javascript-mocha"]:::export
      LangIndex["index.ts"]:::export
      LangCmd["command.ts"]:::export
    end

    %% Migration Tool
    subgraph "Migration Tool"
      direction TB
      MBin["bin.ts"]:::migration
      MLegacy["legacy/migrate.ts"]:::migration
      MRules["migrations"]:::migration
    end

    %% Testing Toolkits
    subgraph "Testing Toolkits"
      direction TB
      STIndex["side-testkit/index.ts"]:::test
      STFixtures["fixtures/static"]:::test
      WDdriver["webdriver-testkit/driver.ts"]:::test
      WDscript["download-drivers.js"]:::test
    end

    %% External Systems
    subgraph "External Systems"
      direction TB
      Browser["Web Browser"]:::external
      FS["File System"]:::external
      Plugins["Plugins"]:::external
      CI["CI/CD"]:::external
      WebDriverSvc["WebDriver Service"]:::external
    end

    %% Connections
    Launcher -->|launches| Main
    Launcher -->|build config| WebpackCfg
    Main -->|spawns windows| Renderer
    Main -->|injects| Preload
    Renderer -->|"side-api IPC"| APIIndex
    Preload -->|"DOM events→IPC"| APIIndex
    APIIndex -->|"implements"| Main
    Main -->|"calls"| RIndex
    RunnerApp -->|"calls"| RIndex
    CLIApp -->|"calls"| RIndex
    RIndex -->|"uses"| GDownload
    RIndex -->|"uses"| GResolve
    RIndex -->|"executes on"| WebDriverSvc
    RunnerApp -->|"WebDriver"| WebDriverSvc
    CLIApp -->|"WebDriver"| WebDriverSvc
    APIIndex -->|"depends on"| ModelCommands
    APIIndex -->|"uses"| CommAsync
    Main -->|"uses"| CommEvents
    Renderer -->|"uses"| CommString
    CEIndex -->|"consumes .side"| ModelCommands
    CEIndex -->|"core pipeline"| CECores
    CECores -->|"language modules"| LanguageMod
    LanguageMod -->|"index"| LangIndex
    LanguageMod -->|"command"| LangCmd
    MLegacy -->|"reads HTML"| FS
    MLegacy -->|"emits .side"| FS
    CEIndex -->|"writes code"| FS
    STIndex -->|"fixtures for"| RunnerApp
    WDdriver -->|"drivers for"| RIndex
    Plugins -->|"extend via"| APIIndex
    CI -->|"build/test"| Launcher

    %% Click Events
    click Main "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/selenium-ide/src/main"
    click Renderer "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/selenium-ide/src/browser"
    click Preload "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/selenium-ide/src/browser/windows"
    click Launcher "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/selenium-ide/bin.js"
    click WebpackCfg "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/selenium-ide/webpack.config.ts"
    click RunnerBin "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-runner/src/bin.ts"
    click RunnerRun "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-runner/src/run.ts"
    click CLIIndex "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-cli/src/index.tsx"
    click CLIComp "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-cli/src/components"
    click RIndex "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-runtime/src/index.ts"
    click RPlayback "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-runtime/src/playback.ts"
    click RTree "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-runtime/src/playback-tree"
    click RWebdriver "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-runtime/src/webdriver.ts"
    click APIIndex "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-api/src/index.ts"
    click APICommands "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-api/src/commands"
    click APIClasses "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-api/src/classes"
    click APIModels "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-api/src/models"
    click ModelCommands "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-model/src/Commands.ts"
    click ModelArgTypes "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-model/src/ArgTypes.ts"
    click ModelI18N "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-model/src/I18N"
    click CommAsync "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-commons/src/async.ts"
    click CommEvents "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-commons/src/events.ts"
    click CommString "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-commons/src/string.ts"
    click GDownload "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/get-driver/src/download-driver.ts"
    click GResolve "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/get-driver/src/resolve-driver.ts"
    click CEIndex "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-code-export/src/index.ts"
    click CECores "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-code-export/src/code-export"
    click LangIndex "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/code-export-javascript-mocha/src/index.ts"
    click LangCmd "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/code-export-javascript-mocha/src/command.ts"
    click MBin "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-migrate/src/bin.ts"
    click MLegacy "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-migrate/src/legacy/migrate.ts"
    click MRules "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-migrate/src/migrations"
    click STIndex "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/side-testkit/src/index.ts"
    click STFixtures "https://github.com/seleniumhq/selenium-ide/tree/trunk/packages/side-testkit/fixtures/static"
    click WDdriver "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/webdriver-testkit/src/driver.ts"
    click WDscript "https://github.com/seleniumhq/selenium-ide/blob/trunk/packages/webdriver-testkit/scripts/download-drivers.js"

    %% Styles
    classDef electron fill:#cfe2f3,stroke:#0366d6,color:#0366d6,stroke-width:1px,shape:roundrect
    classDef cli fill:#d9ead3,stroke:#006400,color:#006400,stroke-width:1px
    classDef shared fill:#fce5cd,stroke:#e69138,color:#e69138,stroke-width:1px
    classDef export fill:#ead1dc,stroke:#c27ba0,color:#c27ba0,stroke-width:1px
    classDef migration fill:#f4cccc,stroke:#cc0000,color:#cc0000,stroke-width:1px
    classDef test fill:#d0e0e3,stroke:#1155cc,color:#1155cc,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#666666,color:#666666,stroke-width:1px,shape:cloud
    class electron,cli,shared,export,migration,test,external fill-opacity:0.3
```
