# 2045matrix/etcher architecture

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

- Interactive diagram: https://gitdiagram.com/2045matrix/etcher
- Repository: https://github.com/2045matrix/etcher

## Overview

##### Project type and purpose
- This is Etcher, a cross-platform desktop application (built on Electron) for flashing OS images to SD cards and USB drives. It comprises a GUI (renderer process), a main process, and a privileged “sidecar” or child-process for low-level tasks (drive scanning, image writing, elevation).

##### File structure
- Top-level:
- lib/gui/app – The renderer code (React/TypeScript) for the UI.
- lib/gui/index.html, preload.ts, renderer.ts – Electron entry points for the renderer process.
- lib/gui/etcher.ts, lib/gui/menu.ts, lib/gui/webapi.ts – The main process’s bootstrap and menu/web-API glue.
- lib/util & lib/shared – Shared business logic (drive scanning, image-writer, permissions, utils, constants).
- Sidecar: package.json’s “pkg-sidecar.json” and tsconfig.sidecar.json configure a separate node process that runs the low-level image-writing code under elevated privileges.
- Configuration: forge.config.ts, webpack.config.ts for Electron Forge/Webpack.
- Tests under tests/gui, tests/shared, tests/util – Unit and E2E specs.
- assets, docs, CI/CD workflows, signing secrets – Packaging and release infrastructure.

##### README for additional insights
- Confirms it is an Electron app, supports Linux, Windows, macOS.
- Mentions safety checks, complete‐write verification, and USB-boot flashing.

a. Main components:
1. Renderer Process (UI):
- React components (drive-selector, flash-results, progress-button, settings, etc.)
- i18n, CSS, models (selection-state, flash-state).
2. Main Process:
- BrowserWindow creation, menu, IPC bridges, window progress APIs, exception reporting, analytics.
3. Preload Script:
- Exposes safe, limited APIs to the renderer (via contextBridge).
4. Sidecar / Child Process:
- Elevated-privilege subprocess for drive scanning and image writing (through lib/util and lib/shared/sudo).
5. Shared Libraries:
- Cross-process modules: drive constraints, permissions, exit codes, messaging.
6. External Services:
- OS APIs: dialog, notifications, network-drive enumeration.
- Analytics endpoint.
- Exception reporter (Sentry or similar).

b. Relationships & interactions:
- Renderer ←→ Preload: UI calls fetchDrives(), flashImage() via exposed API.
- Preload → Main Process (IPC): Sanitized requests forwarded to main.
- Main Process ↔ Sidecar: Spawns the sidecar for privileged operations; communicates over stdio or IPC.
- Sidecar → Shared Modules: Uses util.drive-scanner, util.child-writer, shared/sudo to perform tasks.
- Failures & progress emissions bubble back: Sidecar → Main → Renderer for UI updates.
- External OS API calls from both main and renderer (notifications, dialogs).
- Analytics & exception reporter modules invoked in main or renderer.

c. Architectural patterns / design principles:
- Process separation: Renderer for UI, Main for orchestration, Sidecar for elevation.
- Preload sandbox: Minimizes renderer privileges via contextBridge.
- Shared code: Avoid duplication by centralizing logic in lib/shared and lib/util.
- Event-driven IPC: Asynchronous messages for progress, errors.
- Modular React components: Single Responsibility, composability.

d. Key technologies / frameworks:
- Electron (main, renderer, preload).
- React + TypeScript for UI.
- Electron Forge + Webpack for bundling.
- Node.js child_process / execa for sidecar operations.
- Sudo-prompt or platform-specific elevation modules.
- i18next (or custom i18n) for localization.
- Jest/WebdriverIO for tests.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Renderer Process
    subgraph "Renderer Process" 
        direction TB
        RendererApp["lib/gui/app"]:::ui
        RendererIndex["index.html"]:::ui
        RendererRenderer["renderer.ts"]:::ui
        RendererComponents["components"]:::ui
        RendererModels["models"]:::ui
        RendererPages["pages"]:::ui
    end

    %% Preload
    Preload["preload.ts"]:::orchestration

    %% Main Process
    subgraph "Main Process"
        direction TB
        MainBootstrap["etcher.ts"]:::orchestration
        MainMenu["menu.ts"]:::orchestration
        MainWebapi["webapi.ts"]:::orchestration
    end

    %% Sidecar Process
    subgraph "Sidecar Process"
        direction TB
        SidecarConfig["pkg-sidecar.json\ntsconfig.sidecar.json"]:::sidecar
    end

    %% Shared and Utilities
    subgraph "Shared Modules" 
        direction TB
        Shared["lib/shared"]:::shared
    end

    subgraph "Utility Modules" 
        direction TB
        Util["lib/util"]:::shared
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        ForgeConfig["forge.config.ts"]:::build
        WebpackConfig["webpack.config.ts"]:::build
        SidecarForge["forge.sidecar.ts"]:::build
    end

    %% External Services
    OSAPI["OS APIs (dialog, notifications)"]:::external
    Analytics["Analytics/ExceptionReporter"]:::external

    %% Connections
    RendererApp -->|"loads"| RendererIndex
    RendererApp -->|"bootstraps"| RendererRenderer
    RendererApp --> RendererComponents
    RendererApp --> RendererModels
    RendererApp --> RendererPages
    RendererApp -->|calls| Preload

    Preload -->|"IPC calls"| MainBootstrap

    MainBootstrap --> MainMenu
    MainBootstrap --> MainWebapi
    MainBootstrap -->|spawns| SidecarConfig

    MainBootstrap -->|uses| Shared
    MainBootstrap -->|uses| Util

    SidecarConfig -->|requires| Util
    SidecarConfig -->|requires| Shared

    Shared --> OSAPI
    MainBootstrap --> OSAPI
    RendererApp --> OSAPI

    MainBootstrap -->|sends events| Analytics
    RendererApp -->|sends events| Analytics

    %% Click Events
    click RendererApp "https://github.com/2045matrix/etcher/tree/master/lib/gui/app"
    click RendererIndex "https://github.com/2045matrix/etcher/blob/master/lib/gui/app/index.html"
    click RendererRenderer "https://github.com/2045matrix/etcher/blob/master/lib/gui/app/renderer.ts"
    click RendererComponents "https://github.com/2045matrix/etcher/tree/master/lib/gui/app/components"
    click RendererModels "https://github.com/2045matrix/etcher/tree/master/lib/gui/app/models"
    click RendererPages "https://github.com/2045matrix/etcher/tree/master/lib/gui/app/pages"
    click Preload "https://github.com/2045matrix/etcher/blob/master/lib/gui/app/preload.ts"
    click MainBootstrap "https://github.com/2045matrix/etcher/blob/master/lib/gui/etcher.ts"
    click MainMenu "https://github.com/2045matrix/etcher/blob/master/lib/gui/menu.ts"
    click MainWebapi "https://github.com/2045matrix/etcher/blob/master/lib/gui/webapi.ts"
    click Shared "https://github.com/2045matrix/etcher/tree/master/lib/shared"
    click Util "https://github.com/2045matrix/etcher/tree/master/lib/util"
    click SidecarConfig "https://github.com/2045matrix/etcher/blob/master/pkg-sidecar.json"
    click SidecarConfig "https://github.com/2045matrix/etcher/blob/master/tsconfig.sidecar.json"
    click ForgeConfig "https://github.com/2045matrix/etcher/blob/master/forge.config.ts"
    click WebpackConfig "https://github.com/2045matrix/etcher/blob/master/webpack.config.ts"
    click SidecarForge "https://github.com/2045matrix/etcher/blob/master/forge.sidecar.ts"

    %% Styles
    classDef ui fill:#E8F0FE,stroke:#2A56C6,color:#000;
    classDef orchestration fill:#E6F4EA,stroke:#27632A,color:#000;
    classDef sidecar fill:#FCE8E6,stroke:#C42417,color:#000;
    classDef shared fill:#FFF4CE,stroke:#A28824,color:#000;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#000;
    classDef build fill:#ECEFF1,stroke:#455A64,color:#000;
```
