How hog185/rufus-py works
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.