# gblach/imge architecture

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

- Interactive diagram: https://gitdiagram.com/gblach/imge
- Repository: https://github.com/gblach/imge

## Overview

##### Project type and purpose
- imge is a Rust-based CLI/TUI (text-user-interface) application for writing disk images to drives (and vice versa), with on-the-fly compression/decompression.
- It wraps low-level disk I/O, stream compression, and a curses-style UI to make `dd`-like workflows safer and more user-friendly.

##### File structure
- Top-level files:
- Cargo.toml / Cargo.lock: Rust package definition and dependencies
- README.md: project overview, CLI synopsis, screenshots
- .github/workflows: CI checks (Rust fmt, clippy)
- src/ directory:
- main.rs: entry point; CLI parsing (clap), configuration
- mainloop.rs: TUI event loop, rendering screens, handling keybindings
- imge.rs: core logic for reading/writing streams, compression/decompression, drive enumeration

##### README for additional insights
- Confirms use of TUI (screenshots), CLI options (—all-drives, —from-drive, —verify).
- Mentions gzip/bzip2/xz support → compression crates (flate2, bzip2, xz2).
- No external services; pure local, single-binary tool.

##### Main components
a. CLI Parser (main.rs)
- Reads command-line args via clap
- Builds a Config object
b. TUI Controller (mainloop.rs)
- Initializes terminal backend (tui-rs + crossterm/termion)
- Renders screens: drive list, warnings, progress, verification
- Dispatches user events (keypresses)
c. Core Engine (imge.rs)
- Drive enumeration & selection (platform-specific block-device discovery)
- Image ↔ Drive streaming pipeline
- Source (file or drive) → optional decompressor → I/O buffer → optional compressor → Destination (drive or file)
- Verification step (read-back & checksum compare)
d. OS / System Calls
- Block device read/write (std::fs or lower-level unsafe calls)
- File I/O for .img, .img.gz, .img.bz2, .img.xz
e. Third-party crates
- clap (CLI)
- tui-rs, crossterm (TUI)
- flate2, bzip2, xz2 (compression)
- indicatif or custom progress reporter

##### Relationships & interactions
- User invokes binary → main.rs
- main.rs → parse args → instantiate TuiController & ImgeEngine
- TuiController ↔ User I/O (keypress, selections)
- On “start copy” action: TuiController → ImgeEngine
- ImgeEngine → OS Block I/O & Compression layers → streams data → reports progress back to TuiController
- If --verify: ImgeEngine runs read-back & checksum → passes result to TuiController → final screen

##### Architectural patterns & design principles
- Modular layering: CLI layer → UI layer → Domain/Engine layer → System/OS layer
- Single-process, event-driven architecture
- Stream-based pipeline for on-the-fly (de)compression
- Separation of concerns: UI vs core logic vs I/O

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: User & Terminal
    subgraph "Layer 1: User & Terminal"
        direction TB
        User["User"]:::external
        Terminal["Terminal"]:::external
    end

    %% Layer 2: CLI & TUI modules
    subgraph "Layer 2: CLI & TUI"
        direction TB
        CLIParser["CLI Parser\n(parse args, build Config)"]:::frontend
        TUIController["TUI Controller\n(event loop, render screens)"]:::frontend
    end

    %% Layer 3: Core Engine & Compression
    subgraph "Layer 3: Core Engine & Compression"
        direction TB
        ImgeEngine["Imge Engine\n(drive enum, streaming pipeline, verification)"]:::core
        CompressionModule["Compression Module\n(gzip, bzip2, xz)"]:::core
    end

    %% Layer 4: OS / System Calls
    subgraph "Layer 4: OS / System"
        direction TB
        BlockIO["Block I/O\n(device & file read/write)"]:::system
        OSLayer["OS / std::fs & syscalls"]:::system
    end

    %% External Dependencies & Project Files
    subgraph "Project Files & Dependencies"
        direction TB
        ProjectManifest["Cargo.toml"]:::external
        RustLockfile["Cargo.lock"]:::external
        CIFmt[".github/workflows/rust-check.yml"]:::external
        CIClippy[".github/workflows/rust-clippy.yml"]:::external
        Docs["README.md"]:::external
        Screenshots["screenshots/"]:::external
    end

    %% Connections
    User -->|invokes binary| CLIParser
    CLIParser -->|initialize| TUIController
    TUIController -->|on start copy| ImgeEngine
    ImgeEngine -->|Stream<Bytes>| CompressionModule
    CompressionModule -->|compressed stream| BlockIO
    BlockIO -->|syscall| OSLayer
    OSLayer -->|device/file| BlockIO
    BlockIO -->|data| CompressionModule
    CompressionModule -->|decompressed stream| ImgeEngine
    ImgeEngine -->|ProgressUpdate| TUIController
    ImgeEngine -->|Verify & checksum| TUIController

    %% Project files references
    click CLIParser "https://github.com/gblach/imge/blob/main/src/main.rs"
    click TUIController "https://github.com/gblach/imge/blob/main/src/mainloop.rs"
    click ImgeEngine "https://github.com/gblach/imge/blob/main/src/imge.rs"
    click ProjectManifest "https://github.com/gblach/imge/blob/main/Cargo.toml"
    click RustLockfile "https://github.com/gblach/imge/blob/main/Cargo.lock"
    click CIFmt "https://github.com/gblach/imge/blob/main/.github/workflows/rust-check.yml"
    click CIClippy "https://github.com/gblach/imge/blob/main/.github/workflows/rust-clippy.yml"
    click Docs "https://github.com/gblach/imge/blob/main/README.md"
    click Screenshots "https://github.com/gblach/imge/tree/main/screenshots/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px
    classDef core fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px
    classDef system fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px
    classDef external fill:#fefefe,stroke-dasharray: 5 5,stroke:#bbb,color:#555,stroke-width:1px

    class User,Terminal external
    class BlockIO,OSLayer system
    class CompressionModule,ImgeEngine core
    class CLIParser,TUIController frontend
    class ProjectManifest,RustLockfile,CIFmt,CIClippy,Docs,Screenshots external
```
