# bboe/firebreak architecture

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

- Interactive diagram: https://gitdiagram.com/bboe/firebreak
- Repository: https://github.com/bboe/firebreak

## Overview

firebreak is a USB firmware-transition tool for three Echo models: it identifies the connected device and its current state, plans progress toward an unlock or stock target, then executes recovery, bootloader, and firmware operations. The CLI also offers direct reboot, fastboot, TWRP, and bootrom actions. Device-specific configuration and low-level MediaTek/eMMC access support those stages. The index and excerpts establish the main orchestration links; several capability branches are documented or indexed but their implementation was not sampled, so those links are omitted where unverified.

Main entry points: [`firebreak/route.py`](https://github.com/bboe/firebreak/blob/main/firebreak/route.py) (Transition planner), [`firebreak/__main__.py`](https://github.com/bboe/firebreak/blob/main/firebreak/__main__.py) (Command interface), [`firebreak/bootrom_step.py`](https://github.com/bboe/firebreak/blob/main/firebreak/bootrom_step.py) (Bootrom stage), [`firebreak/host.py`](https://github.com/bboe/firebreak/blob/main/firebreak/host.py) (ADB and fastboot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow and discovery"]
  node_cli["Command interface<br/>[__main__.py]"]
  node_identify["Device detection<br/>[identify.py]"]
  node_entry["State probing<br/>[entry.py]"]
  node_route["Transition planner<br/>[route.py]"]
  node_plugin["Device plans<br/>[plugin.py]"]
  node_states["Device states<br/>[states.py]"]
end

subgraph group_device["Device transitions"]
  node_device_models["Echo models<br/>[biscuit.py]"]
  node_unlock["Unlock workflow<br/>[unlock.py]"]
  node_bootrom_step["Bootrom stage<br/>[bootrom_step.py]"]
  node_kamakiri["Kamakiri stage<br/>[kamakiri_step.py]"]
  node_fireos["Fire OS changes<br/>[fireos.py]"]
  node_recovery["Recovery workflow<br/>[recovery.py]"]
  node_twrp["TWRP operations<br/>[twrp.py]"]
  node_stock["Stock restoration<br/>[stock.py]"]
end

subgraph group_protocol["USB and storage"]
  node_mediatek["MediaTek USB protocol<br/>[usbdl.py]"]
  node_payload["Amonet payload<br/>[payload.py]"]
  node_emmc["eMMC access<br/>[emmc.py]"]
  node_host["ADB and fastboot<br/>[host.py]"]
end

subgraph group_support["Firmware and support"]
  node_cache[("Download cache<br/>[cache.py]")]
  node_backup["Device backup<br/>[backup.py]"]
  node_restore["Backup restore<br/>[restore.py]"]
  node_survey["Device survey<br/>[survey.py]"]
  node_ui["Progress and prompts<br/>[ui.py]"]
end

node_user(("Operator"))
node_adb_service["ADB executable"]
node_fastboot_service["Fastboot executable"]
node_usb_device["Echo over USB"]

node_user -->|"invokes"| node_cli
node_cli -->|"discovers"| node_identify
node_cli -->|"dispatches"| node_route
node_cli -->|"invokes"| node_backup
node_cli -->|"invokes"| node_restore
node_cli -->|"invokes"| node_survey
node_identify -->|"queries"| node_host
node_identify -->|"reports"| node_states
node_entry -->|"checks device"| node_identify
node_entry -->|"runs stage"| node_bootrom_step
node_entry -->|"runs stage"| node_kamakiri
node_entry -->|"checks recovery"| node_twrp
node_entry -->|"invokes"| node_unlock
node_route -->|"dispatches"| node_bootrom_step
node_route -->|"dispatches"| node_kamakiri
node_route -->|"dispatches"| node_fireos
node_route -->|"dispatches"| node_recovery
node_route -->|"dispatches"| node_stock
node_route -->|"uses plans"| node_plugin
node_route -->|"tracks progress"| node_states
node_plugin -->|"defines states"| node_states
node_device_models -->|"configures models"| node_plugin
node_bootrom_step -->|"starts payload"| node_payload
node_bootrom_step -->|"uses protocol"| node_mediatek
node_bootrom_step -->|"accesses storage"| node_emmc
node_payload -->|"uses connection"| node_mediatek
node_kamakiri -->|"uses protocol"| node_mediatek
node_unlock -->|"invokes"| node_bootrom_step
node_unlock -->|"invokes"| node_recovery
node_unlock -->|"invokes"| node_twrp
node_fireos -->|"runs device commands"| node_host
node_fireos -->|"gets artifacts"| node_cache
node_recovery -->|"runs device commands"| node_host
node_recovery -->|"uses recovery"| node_twrp
node_twrp -->|"runs device commands"| node_host
node_host -->|"runs"| node_adb_service
node_host -.->|"runs"| node_fastboot_service
node_identify -->|"scans"| node_usb_device
node_mediatek -.->|"communicates"| node_usb_device
node_cache -->|"reports downloads"| node_ui
node_ui -->|"prompts"| node_user

click node_cli "https://github.com/bboe/firebreak/blob/main/firebreak/__main__.py"
click node_identify "https://github.com/bboe/firebreak/blob/main/firebreak/identify.py"
click node_entry "https://github.com/bboe/firebreak/blob/main/firebreak/entry.py"
click node_route "https://github.com/bboe/firebreak/blob/main/firebreak/route.py"
click node_plugin "https://github.com/bboe/firebreak/blob/main/firebreak/plugin.py"
click node_states "https://github.com/bboe/firebreak/blob/main/firebreak/states.py"
click node_device_models "https://github.com/bboe/firebreak/blob/main/firebreak/devices/biscuit.py"
click node_unlock "https://github.com/bboe/firebreak/blob/main/firebreak/unlock.py"
click node_bootrom_step "https://github.com/bboe/firebreak/blob/main/firebreak/bootrom_step.py"
click node_kamakiri "https://github.com/bboe/firebreak/blob/main/firebreak/kamakiri_step.py"
click node_fireos "https://github.com/bboe/firebreak/blob/main/firebreak/fireos.py"
click node_recovery "https://github.com/bboe/firebreak/blob/main/firebreak/recovery.py"
click node_twrp "https://github.com/bboe/firebreak/blob/main/firebreak/twrp.py"
click node_stock "https://github.com/bboe/firebreak/blob/main/firebreak/stock.py"
click node_mediatek "https://github.com/bboe/firebreak/blob/main/firebreak/mediatek/usbdl.py"
click node_payload "https://github.com/bboe/firebreak/blob/main/firebreak/amonet/payload.py"
click node_emmc "https://github.com/bboe/firebreak/blob/main/firebreak/emmc.py"
click node_host "https://github.com/bboe/firebreak/blob/main/firebreak/host.py"
click node_cache "https://github.com/bboe/firebreak/blob/main/firebreak/cache.py"
click node_backup "https://github.com/bboe/firebreak/blob/main/firebreak/backup.py"
click node_restore "https://github.com/bboe/firebreak/blob/main/firebreak/restore.py"
click node_survey "https://github.com/bboe/firebreak/blob/main/firebreak/survey.py"
click node_ui "https://github.com/bboe/firebreak/blob/main/firebreak/ui.py"

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_cli,node_identify,node_entry,node_route,node_plugin,node_states toneBlue
class node_device_models,node_unlock,node_bootrom_step,node_kamakiri,node_fireos,node_recovery,node_twrp,node_stock toneAmber
class node_mediatek,node_payload,node_emmc,node_host toneMint
class node_cache,node_backup,node_restore,node_survey,node_ui toneRose
class node_user,node_adb_service,node_fastboot_service,node_usb_device toneIndigo
```

## Components

### Workflow and discovery

- [Command interface](https://github.com/bboe/firebreak/blob/main/firebreak/__main__.py): `firebreak/__main__.py`
- [Device detection](https://github.com/bboe/firebreak/blob/main/firebreak/identify.py): `firebreak/identify.py`
- [State probing](https://github.com/bboe/firebreak/blob/main/firebreak/entry.py): `firebreak/entry.py`
- [Transition planner](https://github.com/bboe/firebreak/blob/main/firebreak/route.py): `firebreak/route.py`
- [Device plans](https://github.com/bboe/firebreak/blob/main/firebreak/plugin.py): `firebreak/plugin.py`
- [Device states](https://github.com/bboe/firebreak/blob/main/firebreak/states.py): `firebreak/states.py`

### Device transitions

- [Echo models](https://github.com/bboe/firebreak/blob/main/firebreak/devices/biscuit.py): `firebreak/devices/biscuit.py`
- [Unlock workflow](https://github.com/bboe/firebreak/blob/main/firebreak/unlock.py): `firebreak/unlock.py`
- [Bootrom stage](https://github.com/bboe/firebreak/blob/main/firebreak/bootrom_step.py): `firebreak/bootrom_step.py`
- [Kamakiri stage](https://github.com/bboe/firebreak/blob/main/firebreak/kamakiri_step.py): `firebreak/kamakiri_step.py`
- [Fire OS changes](https://github.com/bboe/firebreak/blob/main/firebreak/fireos.py): `firebreak/fireos.py`
- [Recovery workflow](https://github.com/bboe/firebreak/blob/main/firebreak/recovery.py): `firebreak/recovery.py`
- [TWRP operations](https://github.com/bboe/firebreak/blob/main/firebreak/twrp.py): `firebreak/twrp.py`
- [Stock restoration](https://github.com/bboe/firebreak/blob/main/firebreak/stock.py): `firebreak/stock.py`

### USB and storage

- [MediaTek USB protocol](https://github.com/bboe/firebreak/blob/main/firebreak/mediatek/usbdl.py): `firebreak/mediatek/usbdl.py`
- [Amonet payload](https://github.com/bboe/firebreak/blob/main/firebreak/amonet/payload.py): `firebreak/amonet/payload.py`
- [eMMC access](https://github.com/bboe/firebreak/blob/main/firebreak/emmc.py): `firebreak/emmc.py`
- [ADB and fastboot](https://github.com/bboe/firebreak/blob/main/firebreak/host.py): `firebreak/host.py`

### Firmware and support

- [Download cache](https://github.com/bboe/firebreak/blob/main/firebreak/cache.py): `firebreak/cache.py`
- [Device backup](https://github.com/bboe/firebreak/blob/main/firebreak/backup.py): `firebreak/backup.py`
- [Backup restore](https://github.com/bboe/firebreak/blob/main/firebreak/restore.py): `firebreak/restore.py`
- [Device survey](https://github.com/bboe/firebreak/blob/main/firebreak/survey.py): `firebreak/survey.py`
- [Progress and prompts](https://github.com/bboe/firebreak/blob/main/firebreak/ui.py): `firebreak/ui.py`

### Other components

- **Operator**
- **ADB executable**
- **Fastboot executable**
- **Echo over USB**

## Connections

- Operator → Command interface: invokes (evidence: `README.md`)
- Command interface → Device detection: discovers (evidence: `firebreak/__main__.py`)
- Command interface → Transition planner: dispatches (evidence: `firebreak/__main__.py`)
- Command interface → Device backup: invokes (evidence: `firebreak/__main__.py`)
- Command interface → Backup restore: invokes (evidence: `firebreak/__main__.py`)
- Command interface → Device survey: invokes (evidence: `firebreak/__main__.py`)
- Device detection → ADB and fastboot: queries (evidence: `firebreak/identify.py`)
- Device detection → Device states: reports (evidence: `firebreak/identify.py`)
- State probing → Device detection: checks device (evidence: `firebreak/entry.py`)
- State probing → Bootrom stage: runs stage (evidence: `firebreak/entry.py`)
- State probing → Kamakiri stage: runs stage (evidence: `firebreak/entry.py`)
- State probing → TWRP operations: checks recovery (evidence: `firebreak/entry.py`)
- State probing → Unlock workflow: invokes (evidence: `firebreak/entry.py`)
- Transition planner → Bootrom stage: dispatches (evidence: `firebreak/route.py`)
- Transition planner → Kamakiri stage: dispatches (evidence: `firebreak/route.py`)
- Transition planner → Fire OS changes: dispatches (evidence: `firebreak/route.py`)
- Transition planner → Recovery workflow: dispatches (evidence: `firebreak/route.py`)
- Transition planner → Stock restoration: dispatches (evidence: `firebreak/route.py`)
- Transition planner → Device plans: uses plans (evidence: `firebreak/route.py`)
- Transition planner → Device states: tracks progress (evidence: `firebreak/route.py`)
- Device plans → Device states: defines states (evidence: `firebreak/plugin.py`)
- Echo models → Device plans: configures models (evidence: `firebreak/devices/biscuit.py`)
- Bootrom stage → Amonet payload: starts payload (evidence: `firebreak/bootrom_step.py`)
- Bootrom stage → MediaTek USB protocol: uses protocol (evidence: `firebreak/bootrom_step.py`)
- Bootrom stage → eMMC access: accesses storage (evidence: `firebreak/bootrom_step.py`)
- Amonet payload → MediaTek USB protocol: uses connection (evidence: `firebreak/amonet/payload.py`)
- Kamakiri stage → MediaTek USB protocol: uses protocol (evidence: `firebreak/kamakiri_step.py`)
- Unlock workflow → Bootrom stage: invokes (evidence: `firebreak/unlock.py`)
- Unlock workflow → Recovery workflow: invokes (evidence: `firebreak/unlock.py`)
- Unlock workflow → TWRP operations: invokes (evidence: `firebreak/unlock.py`)
- Fire OS changes → ADB and fastboot: runs device commands (evidence: `firebreak/fireos.py`)
- Fire OS changes → Download cache: gets artifacts (evidence: `firebreak/fireos.py`)
- Recovery workflow → ADB and fastboot: runs device commands (evidence: `firebreak/recovery.py`)
- Recovery workflow → TWRP operations: uses recovery (evidence: `firebreak/recovery.py`)
- TWRP operations → ADB and fastboot: runs device commands (evidence: `firebreak/twrp.py`)
- ADB and fastboot → ADB executable: runs (evidence: `firebreak/host.py`)
- ADB and fastboot → Fastboot executable: runs (evidence: `README.md`)
- Device detection → Echo over USB: scans (evidence: `firebreak/identify.py`)
- MediaTek USB protocol → Echo over USB: communicates (evidence: `README.md`)
- Download cache → Progress and prompts: reports downloads (evidence: `firebreak/cache.py`)
- Progress and prompts → Operator: prompts (evidence: `firebreak/ui.py`)
