# topjohnwu/samloader-rs architecture

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

- Interactive diagram: https://gitdiagram.com/topjohnwu/samloader-rs
- Repository: https://github.com/topjohnwu/samloader-rs

## Overview

samloader combines Samsung firmware lookup/download with device flashing and related PIT, checksum, and device-management commands. The primary workflow starts at the CLI, downloads firmware through FUS, then processes firmware packages and sends partitions over the Odin/Loke protocol to a connected device. The graph also preserves documented capabilities that are not fully visible in the excerpts. Edges without direct source evidence are omitted; the CLI-to-library handoffs are documented at a high level rather than verified in sampled call sites.

Main entry points: [`odin/src/flash.rs`](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/flash.rs) (Flash orchestration), [`odin/src/usb/mod.rs`](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/mod.rs) (Backend selection), [`samloader/src/main.rs`](https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/main.rs) (Command router), [`fus/src/fusclient.rs`](https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/fusclient.rs) (FUS client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["Command router<br/>[main.rs]"]
  node_actions["Command actions<br/>[actions.rs]"]
  node_download["Download commands<br/>[download.rs]"]
  node_flash_cli["Flash commands<br/>[flash.rs]"]
end

subgraph group_fus["Firmware service"]
  node_fusclient["FUS client<br/>[fusclient.rs]"]
  node_auth["FUS authentication<br/>[auth.rs]"]
  node_xml["FUS XML parsing<br/>[xml.rs]"]
  node_fus_download["Firmware transfer<br/>[download.rs]"]
end

subgraph group_flash["Flashing engine"]
  node_flash_manager["Flash orchestration<br/>[flash.rs]"]
  node_firmware["Firmware processing<br/>[firmware.rs]"]
  node_device_info["Device information<br/>[device_info.rs]"]
  node_progress["Progress reporting<br/>[progress.rs]"]
end

subgraph group_transport["Device transport"]
  node_odin_session["Odin session<br/>[odin.rs]"]
  node_protocol["LOKE protocol<br/>[protocol.rs]"]
  node_usb_select["Backend selection<br/>[mod.rs]"]
  node_nusb["nusb backend<br/>[nusb.rs]"]
  node_rusb["libusb backend<br/>[rusb.rs]"]
  node_serial["Serial backend<br/>[serial.rs]"]
  node_mock["Mock backend<br/>[mock.rs]"]
end

subgraph group_pit["PIT handling"]
  node_pit_parser["PIT parsing<br/>[lib.rs]"]
end

node_user(("Operator"))
node_fus_service["Samsung FUS"]
node_phone(("Samsung device"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches actions"| node_actions
node_cli -->|"dispatches downloads"| node_download
node_cli -->|"dispatches flashing"| node_flash_cli
node_actions -->|"uses flash commands"| node_flash_cli
node_download -.->|"requests firmware"| node_fusclient
node_fusclient -->|"uses authentication"| node_auth
node_fusclient -->|"uses XML helpers"| node_xml
node_fusclient -.->|"sends service requests"| node_fus_service
node_fus_download -.->|"downloads firmware"| node_fus_service
node_flash_cli -.->|"starts flashing"| node_flash_manager
node_flash_manager -->|"processes packages"| node_firmware
node_flash_manager -->|"reports progress"| node_progress
node_flash_manager -->|"sends flash operations"| node_odin_session
node_flash_manager -->|"reads PIT data"| node_pit_parser
node_odin_session -->|"queries device"| node_device_info
node_odin_session -->|"encodes commands"| node_protocol
node_odin_session -->|"transfers data"| node_usb_select
node_usb_select -->|"selects backend"| node_nusb
node_usb_select -->|"selects backend"| node_rusb
node_usb_select -->|"selects backend"| node_serial
node_usb_select -->|"selects backend"| node_mock
node_nusb -.->|"communicates with"| node_phone
node_rusb -.->|"communicates with"| node_phone
node_serial -.->|"communicates with"| node_phone

click node_cli "https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/main.rs"
click node_actions "https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/actions.rs"
click node_download "https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/download.rs"
click node_flash_cli "https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/flash.rs"
click node_fusclient "https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/fusclient.rs"
click node_auth "https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/auth.rs"
click node_xml "https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/xml.rs"
click node_fus_download "https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/download.rs"
click node_flash_manager "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/flash.rs"
click node_firmware "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/firmware.rs"
click node_device_info "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/device_info.rs"
click node_progress "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/progress.rs"
click node_pit_parser "https://github.com/topjohnwu/samloader-rs/blob/main/pit/src/lib.rs"
click node_odin_session "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/odin.rs"
click node_protocol "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/protocol.rs"
click node_usb_select "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/mod.rs"
click node_nusb "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/nusb.rs"
click node_rusb "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/rusb.rs"
click node_serial "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/serial.rs"
click node_mock "https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/mock.rs"

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_actions,node_download,node_flash_cli toneBlue
class node_fusclient,node_auth,node_xml,node_fus_download toneAmber
class node_flash_manager,node_firmware,node_device_info,node_progress toneMint
class node_odin_session,node_protocol,node_usb_select,node_nusb,node_rusb,node_serial,node_mock toneRose
class node_pit_parser,node_user,node_fus_service,node_phone toneIndigo
```

## Components

### CLI workflows

- [Command router](https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/main.rs): `samloader/src/main.rs`
- [Command actions](https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/actions.rs): `samloader/src/actions.rs`
- [Download commands](https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/download.rs): `samloader/src/download.rs`
- [Flash commands](https://github.com/topjohnwu/samloader-rs/blob/main/samloader/src/flash.rs): `samloader/src/flash.rs`

### Firmware service

- [FUS client](https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/fusclient.rs): `fus/src/fusclient.rs`
- [FUS authentication](https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/auth.rs): `fus/src/auth.rs`
- [FUS XML parsing](https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/xml.rs): `fus/src/xml.rs`
- [Firmware transfer](https://github.com/topjohnwu/samloader-rs/blob/main/fus/src/download.rs): `fus/src/download.rs`

### Flashing engine

- [Flash orchestration](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/flash.rs): `odin/src/flash.rs`
- [Firmware processing](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/firmware.rs): `odin/src/firmware.rs`
- [Device information](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/device_info.rs): `odin/src/device_info.rs`
- [Progress reporting](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/progress.rs): `odin/src/progress.rs`

### Device transport

- [Odin session](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/odin.rs): `odin/src/odin.rs`
- [LOKE protocol](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/protocol.rs): `odin/src/protocol.rs`
- [Backend selection](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/mod.rs): `odin/src/usb/mod.rs`
- [nusb backend](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/nusb.rs): `odin/src/usb/nusb.rs`
- [libusb backend](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/rusb.rs): `odin/src/usb/rusb.rs`
- [Serial backend](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/serial.rs): `odin/src/usb/serial.rs`
- [Mock backend](https://github.com/topjohnwu/samloader-rs/blob/main/odin/src/usb/mock.rs): `odin/src/usb/mock.rs`

### PIT handling

- [PIT parsing](https://github.com/topjohnwu/samloader-rs/blob/main/pit/src/lib.rs): `pit/src/lib.rs`

### Other components

- **Operator**
- **Samsung FUS**
- **Samsung device**

## Connections

- Operator → Command router: runs commands (evidence: `README.md`)
- Command router → Command actions: dispatches actions (evidence: `samloader/src/main.rs`)
- Command router → Download commands: dispatches downloads (evidence: `samloader/src/main.rs`)
- Command router → Flash commands: dispatches flashing (evidence: `samloader/src/main.rs`)
- Command actions → Flash commands: uses flash commands (evidence: `samloader/src/actions.rs`)
- Download commands → FUS client: requests firmware
- FUS client → FUS authentication: uses authentication (evidence: `fus/src/fusclient.rs`)
- FUS client → FUS XML parsing: uses XML helpers (evidence: `fus/src/fusclient.rs`)
- FUS client → Samsung FUS: sends service requests
- Firmware transfer → Samsung FUS: downloads firmware
- Flash commands → Flash orchestration: starts flashing
- Flash orchestration → Firmware processing: processes packages (evidence: `odin/src/flash.rs`)
- Flash orchestration → Progress reporting: reports progress (evidence: `odin/src/flash.rs`)
- Flash orchestration → Odin session: sends flash operations (evidence: `odin/src/flash.rs`)
- Flash orchestration → PIT parsing: reads PIT data (evidence: `odin/src/flash.rs`)
- Odin session → Device information: queries device (evidence: `odin/src/odin.rs`)
- Odin session → LOKE protocol: encodes commands (evidence: `odin/src/odin.rs`)
- Odin session → Backend selection: transfers data (evidence: `odin/src/odin.rs`)
- Backend selection → nusb backend: selects backend (evidence: `odin/src/usb/mod.rs`)
- Backend selection → libusb backend: selects backend (evidence: `odin/src/usb/mod.rs`)
- Backend selection → Serial backend: selects backend (evidence: `odin/src/usb/mod.rs`)
- Backend selection → Mock backend: selects backend (evidence: `odin/src/usb/mod.rs`)
- nusb backend → Samsung device: communicates with
- libusb backend → Samsung device: communicates with
- Serial backend → Samsung device: communicates with
