# hog185/rufus-py architecture

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

- Interactive diagram: https://gitdiagram.com/hog185/rufus-py
- Repository: https://github.com/hog185/rufus-py

## Overview

##### Project type & purpose (what you’re diagramming)
**Rufus-Py** is a **local desktop utility** (not a service) that:
- discovers **USB/removable drives** on Linux,
- **formats** them,
- **writes (flashes)** an image (likely ISO/DD-style) to the drive,
- includes a **GUI** wrapper.

- a **UI layer**,
- a **core orchestration layer (CLI entrypoint / app controller)**,
- **drive ops modules** that talk to the **Linux OS / system tools**,
- **writing/verification modules** that read image files and write to block devices,
- and a **test harness**.

There is no evidence of client/server, database, or cloud components; the key “external dependencies” are the **host OS**, **block devices**, and any **system commands/libraries** used to enumerate/format/write.

From the tree:

##### Entrypoints
- `src/rufus_py/__main__.py`
Likely the **main entrypoint** for `python -m rufus_py` (CLI or launching GUI).
- `src/rufus_py/gui/start_gui.py`
Likely a dedicated **GUI launcher**.

##### GUI layer
- `src/rufus_py/gui/gui.py`
Your **presentation layer** (widgets, event handlers, user inputs, progress).

##### Writing/flashing & validation
- `src/rufus_py/writing/flash_usb.py`
- `src/rufus_py/writing/check_file_sig.py`

This is your **imaging pipeline**:
- Validate input image file (signature/magic/extension/format checks)
- Write image to raw device (block-level write)
- Possibly verify / sync / eject (implementation-dependent)

##### Tests
- `tests/test_*.py` + `tests/HowToRunTests.md`

##### Build/packaging
- `pyproject.toml`, `uv.lock`, `.python-version`

##### What the README implies (runtime context)
README indicates:
- Linux-first / Linux UX goal
- Drive imaging + formatting utility
- Beta status, likely evolving architecture

- **risk boundaries** (dangerous operations: formatting, raw writes)
- **permission boundary** (often requires root/admin or polkit)
- **OS integration** (udev, lsblk, /dev nodes, mount/umount, mkfs, dd-like writes)

##### GUI Application (rufus_py.gui)
- `gui.py`
- `start_gui.py`
##### Application Entrypoint / Controller
- `__main__.py`
- (and any coordination logic implied there)
##### Drive Management Subsystem (rufus_py.drives)
- `find_usb.py`
- `get_usb_info.py`
- `formatting.py`
- `states.py`
##### Imaging/Writing Subsystem (rufus_py.writing)
- `check_file_sig.py`
- `flash_usb.py`
##### Host OS / External Interfaces
- Linux kernel block devices (`/dev/sdX`)
- mount/umount subsystem
- formatting tools / filesystem utilities
- device enumeration (udev/lsblk-like)
##### Tests (pytest)
- They call into the modules and may mock OS calls

- **Logging/Progress Reporting** channel (GUI progress bar, stdout)
- **Privilege escalation boundary** (root required)

**GUI flow**
- User → GUI: selects image file, selects target USB, clicks “Format/Flash”
- GUI → Drive subsystem: enumerate drives, refresh list, get details
- GUI → Writing subsystem: validate image, flash to device
- GUI ↔ Controller: orchestrates long-running tasks, cancellation, progress updates

**Drive discovery & info**
- Drive subsystem → Host OS: list devices, query attributes
- Host OS → Drive subsystem: device list/info
- Drive subsystem → GUI: present candidates + warnings (size/model)

**Formatting**
- GUI/Controller → formatting.py: format target
- formatting.py → Host OS utilities: unmount, partition, mkfs
- Host OS → formatting.py: success/failure codes
- formatting.py → GUI: status/progress/errors

**Flashing**
- GUI/Controller → check_file_sig.py: validate image file
- GUI/Controller → flash_usb.py: write image to `/dev/...`
- flash_usb.py → Host OS: raw block write, sync, possibly verify
- flash_usb.py → GUI: progress + completion/errors

**Testing**
- pytest → modules: find_usb/get_usb_info/formatting/check_file_sig
- tests → mocked OS layer: ensure deterministic results

##### Architectural patterns present
Given the layout, the natural patterns to call out visually:
- **Layering**: UI → “core ops modules” → OS interfaces → hardware
- **Subsystem separation**: `drives/*` vs `writing/*` (good to show as two major domains)
- **State modeling**: `drives/states.py` suggests an internal state machine—show it as shared types used by GUI/controller + drive ops.

##### Technologies/libraries to annotate (even if not explicitly listed)
- **Python** application packaged via `pyproject.toml`
- **Linux block device layer** (`/dev/*`)
- **System commands/APIs** (generic) for device enumeration + formatting
- **pytest** for tests

##### System Context / Deployment View (single host)
- “Linux Machine” as the container boundary
- Inside: Rufus-Py process (GUI + modules)
- Outside/adjacent: image file, OS, USB hardware

##### Diagramming conventions to use (make it principal-engineer grade)
Include:
- **Clear labels**: use module names as labels (`flash_usb.py`, `formatting.py`) and also responsibilities (“Raw write to block device”).
- “enumerate devices”, “unmount”, “mkfs”, “write blocks”, “sync”, “report progress”
- Blue: UI / user interaction
- Green: core Python modules (drives/writing)
- Orange: OS/system interfaces
- Gray: physical devices & files
- Red outline: destructive operations (format/flash)
- **Trust/permission boundary**:
- Formatting + raw writing across/within that boundary

- `__main__.py` (entrypoint / mode selection)
- `gui/start_gui.py` (GUI bootstrap)
- `gui/gui.py` (UI + event handlers)
- `drives/find_usb.py` (enumeration)
- `drives/get_usb_info.py` (attributes)
- `drives/formatting.py` (format workflow)
- `drives/states.py` (state definitions)
- `writing/check_file_sig.py` (image validation)
- `writing/flash_usb.py` (block writing)
- “Linux OS APIs / system commands”
- “/dev block devices”
- “USB drive hardware”
- “Image file (ISO/IMG)”

- **C4 Level 1 (Context):** User ↔ Rufus-Py ↔ Linux OS ↔ USB drive; Rufus-Py ↔ Image file.
- **C4 Level 2 (Container/Component):** break Rufus-Py into GUI, drives subsystem, writing subsystem, shared states, entrypoints; show OS boundary and privilege boundary.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% C4 L1 - System Context
%% =========================
subgraph "C4 Level 1 — System Context (Single Linux Host)"
direction TB

U["User"]:::external

subgraph "Linux Machine"
direction TB

APP["Rufus-Py (Local Desktop Utility)\nDiscover • Format • Flash USB"]:::app

OS["Linux OS\n(kernel block layer, mount/umount,\ndevice enumeration, filesystem tools)"]:::os

DEV["/dev Block Devices\n(e.g., /dev/sdX)"]:::os
end

IMG["Image File on Disk\n(ISO/IMG)"]:::artifact
USB["Physical USB Drive"]:::hardware

U -->|"selectsImage+targetDrive"| APP
APP -->|"reads"| IMG
APP -->|"enumerate+format+flash"| OS
OS -->|"exposes"| DEV
DEV -->|"mapsTo"| USB
end

%% =========================
%% C4 L2 - Component View
%% =========================
subgraph "C4 Level 2 — Component View (rufus_py)"
direction TB

subgraph "Entrypoints / Control Flow"
direction TB
MAIN["__main__.py\nEntrypoint / mode selection\n(orchestration controller)"]:::controller
GUIBOOT["start_gui.py\nGUI bootstrap / launcher"]:::ui
end

subgraph "GUI Layer (Presentation)"
direction TB
GUI["gui.py\nWidgets • Event handlers\nProgress • Cancel • Errors"]:::ui
end

subgraph "Domain: Drive Management (rufus_py.drives)"
direction TB
DRIVES_PKG["drives/ (package)"]:::pkg

FIND["find_usb.py\nDiscover/removable filtering"]:::core
INFO["get_usb_info.py\nAttributes: model/size/fs/mounts"]:::core
STATES["states.py\nState machine / enums"]:::core
FMT["formatting.py\nUnmount • partition • mkfs\n(Destructive)"]:::danger
end

subgraph "Domain: Imaging / Writing (rufus_py.writing)"
direction TB
WRITING_PKG["writing/ (package)"]:::pkg

SIG["check_file_sig.py\nValidate image signature/format"]:::core
FLASH["flash_usb.py\nRaw write blocks • sync\n(Destructive)"]:::danger
end

subgraph "External Interfaces (Host OS + Hardware)"
direction TB
PERM["Privilege Boundary\n(root/admin often required)"]:::boundary
SYS["Linux system commands/APIs\n(device enumeration, mount/umount, mkfs, io)"]:::os
BLK["/dev/sdX Block Device Node"]:::os
HW["USB Drive Hardware"]:::hardware
FILE["Image File (ISO/IMG)"]:::artifact
end

%% --- control flow ---
MAIN -->|"launchGUI"| GUIBOOT
GUIBOOT -->|"initUI"| GUI

%% --- UI to subsystems ---
GUI -->|"refreshDrives"| FIND
GUI -->|"getDetails"| INFO
GUI -->|"useStates"| STATES
GUI -->|"formatSelectedDrive"| FMT
GUI -->|"validateImage"| SIG
GUI -->|"flashImage"| FLASH

%% --- internal package relationships ---
DRIVES_PKG --> FIND
DRIVES_PKG --> INFO
DRIVES_PKG --> STATES
DRIVES_PKG --> FMT

WRITING_PKG --> SIG
WRITING_PKG --> FLASH

FMT -->|"usesStates"| STATES
INFO -->|"usesStates"| STATES

%% --- OS interactions ---
FIND -->|"enumerateDevices"| SYS
INFO -->|"queryAttributes"| SYS

FMT -->|"unmount+partition+mkfs"| PERM
FLASH -->|"rawWrite+sync"| PERM

PERM -->|"executes"| SYS
SYS -->|"reads/writes"| BLK
BLK -->|"represents"| HW

SIG -->|"reads"| FILE
FLASH -->|"reads"| FILE

%% --- progress & results ---
FMT -->|"status+errors"| GUI
FLASH -->|"progress+completion"| GUI
end

%% =========================
%% Testing & Packaging
%% =========================
subgraph "Quality (pytest)"
direction TB
TESTS["tests/ (pytest test suite)"]:::test
T_SIG["test_check_file_sig.py"]:::test
T_FIND["test_find_usb.py"]:::test
T_FMT["test_formatting.py"]:::test
T_INFO["test_get_usb_info.py"]:::test
HOW["HowToRunTests.md"]:::doc
end

subgraph "Build & Packaging"
direction TB
PYPROJ["pyproject.toml"]:::build
UV["uv.lock"]:::build
PYVER[".python-version"]:::build
end

TESTS --> T_SIG
TESTS --> T_FIND
TESTS --> T_FMT
TESTS --> T_INFO
TESTS --> HOW

T_SIG -->|"calls"| SIG
T_FIND -->|"calls"| FIND
T_FMT -->|"calls"| FMT
T_INFO -->|"calls"| INFO

%% Tests often mock OS calls
TESTS -.->|"mocksOSCalls"| SYS

PYPROJ -->|"definesPackage+deps"| APP
UV -->|"pinsDependencies"| APP
PYVER -->|"pinsPythonVersion"| APP

%% =========================
%% Click Events (from mapping)
%% =========================
click MAIN "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/__main__.py"
click GUIBOOT "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/gui/start_gui.py"
click GUI "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/gui/gui.py"

click DRIVES_PKG "https://github.com/hog185/rufus-py/tree/main/src/rufus_py/drives/"
click FIND "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/drives/find_usb.py"
click INFO "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/drives/get_usb_info.py"
click FMT "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/drives/formatting.py"
click STATES "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/drives/states.py"

click WRITING_PKG "https://github.com/hog185/rufus-py/tree/main/src/rufus_py/writing/"
click SIG "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/writing/check_file_sig.py"
click FLASH "https://github.com/hog185/rufus-py/blob/main/src/rufus_py/writing/flash_usb.py"

click TESTS "https://github.com/hog185/rufus-py/tree/main/tests/"
click T_SIG "https://github.com/hog185/rufus-py/blob/main/tests/test_check_file_sig.py"
click T_FIND "https://github.com/hog185/rufus-py/blob/main/tests/test_find_usb.py"
click T_FMT "https://github.com/hog185/rufus-py/blob/main/tests/test_formatting.py"
click T_INFO "https://github.com/hog185/rufus-py/blob/main/tests/test_get_usb_info.py"
click HOW "https://github.com/hog185/rufus-py/blob/main/tests/HowToRunTests.md"

click PYPROJ "https://github.com/hog185/rufus-py/blob/main/pyproject.toml"
click UV "https://github.com/hog185/rufus-py/blob/main/uv.lock"
click PYVER "https://github.com/hog185/rufus-py/blob/main/.python-version"

%% =========================
%% Styles
%% =========================
classDef external fill:#E6E6E6,stroke:#666,stroke-width:1px,color:#111
classDef app fill:#B9D9FF,stroke:#2B6CB0,stroke-width:2px,color:#0B2545
classDef controller fill:#A7C7FF,stroke:#1E4E8C,stroke-width:2px,color:#0B2545
classDef ui fill:#8EC5FF,stroke:#1E4E8C,stroke-width:2px,color:#0B2545
classDef core fill:#BFF0C2,stroke:#2F855A,stroke-width:2px,color:#0B2E13
classDef pkg fill:#D7F7D9,stroke:#2F855A,stroke-width:1px,color:#0B2E13
classDef os fill:#FFD6A6,stroke:#C05621,stroke-width:2px,color:#3B1D0E
classDef boundary fill:#FFE0E0,stroke:#C53030,stroke-width:2px,stroke-dasharray:6 4,color:#5A0B0B
classDef danger fill:#FFC1C1,stroke:#C53030,stroke-width:3px,color:#5A0B0B
classDef hardware fill:#D1D5DB,stroke:#4B5563,stroke-width:2px,color:#111827
classDef artifact fill:#E5E7EB,stroke:#6B7280,stroke-width:2px,color:#111827
classDef test fill:#E9D5FF,stroke:#6B21A8,stroke-width:2px,color:#2E1065
classDef doc fill:#F3E8FF,stroke:#6B21A8,stroke-width:1px,color:#2E1065
classDef build fill:#FFF3B0,stroke:#B7791F,stroke-width:2px,color:#3B2F0B
```
