# balena-io/etcher architecture

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

- Interactive diagram: https://gitdiagram.com/balena-io/etcher
- Repository: https://github.com/balena-io/etcher

## Overview

Etcher is an Electron desktop app for safely flashing OS images to SD cards and USB drives. The main user workflow is to choose an image or source, select a destination, flash it, and review the outcome; the README also highlights write verification and Raspberry Pi USB device boot support. The source index confirms the UI entry point and a WebSocket-backed utility API that dispatches scanning, metadata lookup, and writing. Some UI-to-backend wiring and the flash engine’s internal verification path were not shown, so those links are omitted or marked unverified.

Main entry points: [`lib/gui/app/pages/main/MainPage.tsx`](https://github.com/balena-io/etcher/blob/master/lib/gui/app/pages/main/MainPage.tsx) (Main page), [`lib/gui/app/app.ts`](https://github.com/balena-io/etcher/blob/master/lib/gui/app/app.ts) (App bootstrap), [`lib/util/api.ts`](https://github.com/balena-io/etcher/blob/master/lib/util/api.ts) (Utility API), [`lib/gui/app/components/source-selector/source-selector.tsx`](https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/source-selector/source-selector.tsx) (Source selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_shell["Electron shell<br/>[etcher.ts]"]
  node_app["App bootstrap<br/>[app.ts]"]
end

subgraph group_workflow["Flash workflow"]
  node_mainpage["Main page<br/>[MainPage.tsx]"]
  node_source["Source selection"]
  node_destination["Drive selection<br/>[drive-selector.tsx]"]
  node_target["Target selection"]
  node_state["Workflow state<br/>[store.ts]"]
  node_flashstate["Flash progress<br/>[flash-state.ts]"]
  node_results["Flash results<br/>[flash-results.tsx]"]
  node_flash["Flash page<br/>[Flash.tsx]"]
  node_constraints["Drive safety rules"]
end

subgraph group_engine["Flash services"]
  node_service["Utility API<br/>[api.ts]"]
  node_writer["Image writer<br/>[child-writer.ts]"]
  node_scanner["Drive scanner<br/>[scanner.ts]"]
  node_metadata["Source metadata<br/>[source-metadata.ts]"]
end

subgraph group_platform["Platform support"]
  node_settings[("User settings<br/>[settings.ts]")]
  node_analytics["Analytics<br/>[analytics.ts]"]
end

node_user(("User"))
node_pi["Raspberry Pi USB boot"]
node_verification["Write verification"]

node_user -->|"uses"| node_mainpage
node_app -->|"renders"| node_mainpage
node_mainpage -->|"renders"| node_source
node_mainpage -->|"renders"| node_target
node_source -->|"offers source-drive choice"| node_destination
node_mainpage -->|"renders"| node_flash
node_source -->|"updates selection"| node_state
node_destination -->|"updates selection"| node_state
node_destination -->|"checks drive status"| node_constraints
node_app -->|"observes progress"| node_flashstate
node_flash -.->|"presents outcome"| node_results
node_service -->|"dispatches writes"| node_writer
node_service -->|"starts scans"| node_scanner
node_service -->|"requests metadata"| node_metadata
node_mainpage -->|"uses settings"| node_settings
node_app -->|"initializes analytics"| node_analytics
node_writer -.->|"verifies written data"| node_verification
node_writer -.->|"supports USB device boot"| node_pi

click node_shell "https://github.com/balena-io/etcher/blob/master/lib/gui/etcher.ts"
click node_app "https://github.com/balena-io/etcher/blob/master/lib/gui/app/app.ts"
click node_mainpage "https://github.com/balena-io/etcher/blob/master/lib/gui/app/pages/main/MainPage.tsx"
click node_source "https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/source-selector/source-selector.tsx"
click node_destination "https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/drive-selector/drive-selector.tsx"
click node_target "https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/target-selector/target-selector.tsx"
click node_state "https://github.com/balena-io/etcher/blob/master/lib/gui/app/models/store.ts"
click node_flashstate "https://github.com/balena-io/etcher/blob/master/lib/gui/app/models/flash-state.ts"
click node_results "https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/flash-results/flash-results.tsx"
click node_flash "https://github.com/balena-io/etcher/blob/master/lib/gui/app/pages/main/Flash.tsx"
click node_constraints "https://github.com/balena-io/etcher/blob/master/lib/shared/drive-constraints.ts"
click node_service "https://github.com/balena-io/etcher/blob/master/lib/util/api.ts"
click node_writer "https://github.com/balena-io/etcher/blob/master/lib/util/child-writer.ts"
click node_scanner "https://github.com/balena-io/etcher/blob/master/lib/util/scanner.ts"
click node_metadata "https://github.com/balena-io/etcher/blob/master/lib/util/source-metadata.ts"
click node_settings "https://github.com/balena-io/etcher/blob/master/lib/gui/app/models/settings.ts"
click node_analytics "https://github.com/balena-io/etcher/blob/master/lib/gui/app/modules/analytics.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shell,node_app,node_user toneBlue
class node_mainpage,node_source,node_destination,node_target,node_state,node_flashstate,node_results,node_flash,node_constraints toneAmber
class node_service,node_writer,node_scanner,node_metadata toneMint
class node_settings,node_analytics toneRose
class node_pi,node_verification toneIndigo
```

## Components

### Desktop experience

- [Electron shell](https://github.com/balena-io/etcher/blob/master/lib/gui/etcher.ts): `lib/gui/etcher.ts`
- [App bootstrap](https://github.com/balena-io/etcher/blob/master/lib/gui/app/app.ts): `lib/gui/app/app.ts`

### Flash workflow

- [Main page](https://github.com/balena-io/etcher/blob/master/lib/gui/app/pages/main/MainPage.tsx): `lib/gui/app/pages/main/MainPage.tsx`
- [Source selection](https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/source-selector/source-selector.tsx): `lib/gui/app/components/source-selector/source-selector.tsx`
- [Drive selection](https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/drive-selector/drive-selector.tsx): `lib/gui/app/components/drive-selector/drive-selector.tsx`
- [Target selection](https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/target-selector/target-selector.tsx): `lib/gui/app/components/target-selector/target-selector.tsx`
- [Workflow state](https://github.com/balena-io/etcher/blob/master/lib/gui/app/models/store.ts): `lib/gui/app/models/store.ts`
- [Flash progress](https://github.com/balena-io/etcher/blob/master/lib/gui/app/models/flash-state.ts): `lib/gui/app/models/flash-state.ts`
- [Flash results](https://github.com/balena-io/etcher/blob/master/lib/gui/app/components/flash-results/flash-results.tsx): `lib/gui/app/components/flash-results/flash-results.tsx`
- [Flash page](https://github.com/balena-io/etcher/blob/master/lib/gui/app/pages/main/Flash.tsx): `lib/gui/app/pages/main/Flash.tsx`
- [Drive safety rules](https://github.com/balena-io/etcher/blob/master/lib/shared/drive-constraints.ts): `lib/shared/drive-constraints.ts`

### Flash services

- [Utility API](https://github.com/balena-io/etcher/blob/master/lib/util/api.ts): `lib/util/api.ts`
- [Image writer](https://github.com/balena-io/etcher/blob/master/lib/util/child-writer.ts): `lib/util/child-writer.ts`
- [Drive scanner](https://github.com/balena-io/etcher/blob/master/lib/util/scanner.ts): `lib/util/scanner.ts`
- [Source metadata](https://github.com/balena-io/etcher/blob/master/lib/util/source-metadata.ts): `lib/util/source-metadata.ts`

### Platform support

- [User settings](https://github.com/balena-io/etcher/blob/master/lib/gui/app/models/settings.ts): `lib/gui/app/models/settings.ts`
- [Analytics](https://github.com/balena-io/etcher/blob/master/lib/gui/app/modules/analytics.ts): `lib/gui/app/modules/analytics.ts`

### Other components

- **User**
- **Raspberry Pi USB boot**
- **Write verification**

## Connections

- User → Main page: uses
- App bootstrap → Main page: renders (evidence: `lib/gui/app/app.ts`)
- Main page → Source selection: renders (evidence: `lib/gui/app/pages/main/MainPage.tsx`)
- Main page → Target selection: renders (evidence: `lib/gui/app/pages/main/MainPage.tsx`)
- Source selection → Drive selection: offers source-drive choice (evidence: `lib/gui/app/components/source-selector/source-selector.tsx`)
- Main page → Flash page: renders (evidence: `lib/gui/app/pages/main/MainPage.tsx`)
- Source selection → Workflow state: updates selection (evidence: `lib/gui/app/components/source-selector/source-selector.tsx`)
- Drive selection → Workflow state: updates selection (evidence: `lib/gui/app/components/drive-selector/drive-selector.tsx`)
- Drive selection → Drive safety rules: checks drive status (evidence: `lib/gui/app/components/drive-selector/drive-selector.tsx`)
- App bootstrap → Flash progress: observes progress (evidence: `lib/gui/app/app.ts`)
- Flash page → Flash results: presents outcome
- Utility API → Image writer: dispatches writes (evidence: `lib/util/api.ts`)
- Utility API → Drive scanner: starts scans (evidence: `lib/util/api.ts`)
- Utility API → Source metadata: requests metadata (evidence: `lib/util/api.ts`)
- Main page → User settings: uses settings (evidence: `lib/gui/app/pages/main/MainPage.tsx`)
- App bootstrap → Analytics: initializes analytics (evidence: `lib/gui/app/app.ts`)
- Image writer → Write verification: verifies written data
- Image writer → Raspberry Pi USB boot: supports USB device boot
