# thesourcerer8/hddsuperclone architecture

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

- Interactive diagram: https://gitdiagram.com/thesourcerer8/hddsuperclone
- Repository: https://github.com/thesourcerer8/hddsuperclone

## Overview

##### Project type and purpose
- hddsuperclone is a native C-based desktop toolset for low-level HDD/SSD cloning, repair and analysis. It comprises three primary user-space applications (HDDSuperClone, HDDSuperTool, HDDSCViewer), a custom kernel driver (AHCI/virtual disk), shell scripts (for ATA commands and packaging), UI definitions (Glade), multi-language support, and a Live-CD builder that bundles in third-party recovery tools.

##### High-level architectural layers
- Presentation layer: GTK-3 UI definitions (Glade .glade files), command-line interface.
- Application logic: core libraries and modules (common.c/h, commands.c/h, io.c/h, usbrelay.c/h, clone_gui_*.c/h).
- Hardware interface: libusb-based direct mode + custom kernel driver (driver/hddsuperclone_driver.c).
- Scripting & packaging: hddscripts/ and myscripts/ (ATA command wrappers), Makefiles and shell scripts to build, install, package, produce Live CD.
- External components: xxd (resource embedding), libusb-dev, libgtk-3-dev, libbsd, linux headers, libcurl (optional), help2man, texinfo, third-party binaries (ddrescue, ddrescueview, ddrutility, DMDE, hdparm, isolinux).

##### Main components and relationships
a. Code modules
- Core library modules (common, commands, IO, USB relay)
- UI layer (clone_gui_language, clone_gui_common, clone_gui2/3) compiled with libgtk-3
- Kernel driver compiled against linux-headers
- Language file resources embedded via xxd
b. Build system
- Top-level Makefile (and sub-Makefiles under driver/, public/, live_cd/)
- Invokes xxd to embed .glade and driver firmware into C arrays
- Links against libusb, libgtk-3, libbsd, libcurl, generates binaries (hddsuperclone, hddsupertool, hddscviewer) and kernel module
c. Runtime on host OS
- Kernel loads hddsuperclone_driver.ko
- User invokes CLI or clicks GTK UI
- UI → application logic → hardware interface (via libusb or ioctl to driver) → raw block device
d. Scripting and packaging
- hddscripts/ and myscripts/ orchestrate device discovery, ATA commands, cloning workflows by calling the binaries or issuing direct hdparm calls
- Packaging scripts (makeclone.sh, makepublicclone.sh, makelivecd.sh, etc.) assemble distribution archives, Debian/RedHat packages, Live CD ISO
- public/ directory contains prebuilt “public” release artifacts and EULA, news, changelogs, installers
e. Live CD distribution
- Live-CD build includes isolinux bootloader, generic launch scripts, our tools + upstream ddrescue, ddrescueview, ddrutility, DMDE, hdparm

##### Important architectural patterns and design principles
- Layered architecture with clear separation: UI, application core, hardware interface
- Resource embedding (xxd) to package glade/XML and firmware into single binary
- Modular shell scripting for ATA subcommands (reusable good_subroutines)
- Multi-language strategy: directory per language, loaded at runtime
- Packaging pipeline that reuses code modules, scripts, and third-party executables

##### Essential elements
- Source code directories (core/, driver/, ui/, languages/)
- Build system (Makefile, xxd)
- External dependencies (libusb, libgtk-3, linux-headers, xxd)
- Binaries (hddsuperclone, hddsupertool, hddscviewer) and driver module
- Shell scripts (hddscripts/, myscripts/, packaging scripts)
- Runtime flow: UI/CLI → core logic → hardware interface → disk
- Live-CD assembly: isolinux, our tools + ddrescue, ddrescueview, ddrutility, DMDE, hdparm

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Build Time Layer (Blue)
  subgraph "Build Time"
    direction TB
    subgraph "Source Code" 
      direction TB
      Common["common.c/.h"]:::blue
      Commands["commands.c/.h"]:::blue
      IO["io.c/.h"]:::blue
      USBRelay["usbrelay.c/.h"]:::blue
      CloneGUI2["clone_gui2.c/.h"]:::blue
      CloneGUI3["clone_gui3.c/.h"]:::blue
      CloneGUICommon["clone_gui_common.c/.h"]:::blue
      CloneGUILang["clone_gui_language.c/.h"]:::blue
      SCUIGlade2["hddsuperclone2.glade"]:::blue
      SCUIGlade3["hddsuperclone3.glade"]:::blue
      SCViewerGlade2["hddscviewer2.glade"]:::blue
      SCViewerGlade3["hddscviewer3.glade"]:::blue
      SCUICloneC["hddsuperclone.c/.h"]:::blue
      SCUIToolC["hddsupertool.c/.h"]:::blue
      SCUIView2C["hddscviewer2.c/.h"]:::blue
      SCUIView3C["hddscviewer3.c/.h"]:::blue
      DriverSrc["driver/hddsuperclone_driver.c"]:::blue
    end
    Makefiles["Makefile(s)"]:::blue
    Xxd["xxd"]:::blue
    ExternalDeps["libusb, libgtk-3, libbsd, linux-headers, libcurl"]:::blue
    Makefiles -->|orchestrates| Xxd
    Xxd -->|embeds resources| Common
    Common -->|compiled| Compile[Compiler]:::blue
    Commands --> Compile
    IO --> Compile
    USBRelay --> Compile
    CloneGUI2 --> Compile
    CloneGUI3 --> Compile
    CloneGUICommon --> Compile
    CloneGUILang --> Compile
    SCUIGlade2 --> Compile
    SCUIGlade3 --> Compile
    SCViewerGlade2 --> Compile
    SCViewerGlade3 --> Compile
    SCUICloneC --> Compile
    SCUIToolC --> Compile
    SCUIView2C --> Compile
    SCUIView3C --> Compile
    DriverSrc -->|compiles| DriverCompile[Driver Build]:::blue
    Makefiles -->|triggers| DriverCompile
    Compile -->|links| HDDCloneBin["hddsuperclone"]:::green
    Compile -->|links| HDDToolBin["hddsupertool"]:::green
    Compile -->|links| HDDViewerBin["hddscviewer"]:::green
    DriverCompile -->|builds| KernelModule["hddsuperclone_driver.ko"]:::orange
    %% Scripting & Packaging (Gray)
    subgraph "Scripts & Packaging" 
      direction TB
      HDDscripts["hddscripts/"]:::gray
      MyScripts["myscripts/"]:::gray
      PackagingScripts["makeclone.sh, makepublicclone.sh, makepublicviewer.sh, makelivecd.sh, makelivecdx64.sh, makeviewer.sh, cleanpublic*.sh, cleanpro.sh"]:::gray
      HDDCloneBin --> PackagingScripts
      HDDToolBin --> PackagingScripts
      HDDViewerBin --> PackagingScripts
      KernelModule --> PackagingScripts
      HDDscripts --> PackagingScripts
      MyScripts --> PackagingScripts
      PackagingScripts -->|generates| PublicArtifacts["public/ artifacts"]:::gray
      PackagingScripts -->|builds| LiveCDISO["Live CD ISO"]:::purple
    end
  end

  %% Runtime Layer
  subgraph "Runtime / Deployment"
    direction TB
    InstalledBinaries["Installed Binaries"]:::green
    InstalledBinaries --> UI["UI (GTK)"]:::green
    InstalledBinaries --> CLI["CLI"]:::green
    UI --> CoreLogic["Core Logic"]:::green
    CLI --> CoreLogic
    CoreLogic --> HardwareIF["libusb or ioctl(driver)"]:::green
    HardwareIF --> Disk["HDD/SSD"]:::cylinder
    ScriptsRuntime["Runtime Shell Scripts (hddscripts/myscripts)"]:::gray
    ScriptsRuntime -->|invoke| InstalledBinaries
    ScriptsRuntime -->|direct hdparm| Disk
    KernelModule -->|loaded by OS| HardwareIF
  end

  %% Live-CD Distribution
  subgraph "Live-CD Distribution"
    direction TB
    IsoChecksum["livecd.iso.checksum"]:::purple
    Bootloader["isolinux.cfg, isolinux64.cfg, gfxboot*.cfg, txt*.cfg"]:::purple
    GenericLaunch["generic-script.sh"]:::purple
    ThirdParty["ddrescue, ddrescueview, ddrutility, DMDE, hdparm"]:::purple
    LiveCDISO --> IsoChecksum
    LiveCDISO --> Bootloader
    LiveCDISO --> GenericLaunch
    LiveCDISO --> ThirdParty
  end

  %% Click Events
  click CloneGUI2 "https://github.com/thesourcerer8/hddsuperclone/blob/main//clone_gui2.c"
  click CloneGUICommon "https://github.com/thesourcerer8/hddsuperclone/blob/main//clone_gui_common.c"
  click CloneGUILang "https://github.com/thesourcerer8/hddsuperclone/blob/main//clone_gui_language.c"
  click CloneGUI3 "https://github.com/thesourcerer8/hddsuperclone/blob/main//clone_gui3.c"
  click SCUIGlade2 "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddsuperclone2.glade"
  click SCUIGlade3 "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddsuperclone3.glade"
  click SCViewerGlade2 "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddscviewer2.glade"
  click SCViewerGlade3 "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddscviewer3.glade"
  click SCUICloneC "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddsuperclone.c"
  click SCUIToolC "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddsupertool.c"
  click SCUIView2C "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddscviewer2.c"
  click SCUIView3C "https://github.com/thesourcerer8/hddsuperclone/blob/main//hddscviewer3.c"
  click Common "https://github.com/thesourcerer8/hddsuperclone/blob/main//common.c"
  click Commands "https://github.com/thesourcerer8/hddsuperclone/blob/main//commands.c"
  click IO "https://github.com/thesourcerer8/hddsuperclone/blob/main//io.c"
  click USBRelay "https://github.com/thesourcerer8/hddsuperclone/blob/main//usbrelay.c"
  click DriverSrc "https://github.com/thesourcerer8/hddsuperclone/blob/main//driver/hddsuperclone_driver.c"
  click DriverCompile "https://github.com/thesourcerer8/hddsuperclone/tree/main//driver/Makefile"
  click HDDscripts "https://github.com/thesourcerer8/hddsuperclone/tree/main//hddscripts/"
  click MyScripts "https://github.com/thesourcerer8/hddsuperclone/tree/main//myscripts/"
  click PackagingScripts "https://github.com/thesourcerer8/hddsuperclone/blob/main//makeclone.sh"
  click PublicArtifacts "https://github.com/thesourcerer8/hddsuperclone/tree/main//public/base/hddsuperclone/"
  click LiveCDISO "https://github.com/thesourcerer8/hddsuperclone/blob/main//livecd.iso.checksum"

  %% Styles
  classDef blue fill:#ADD8E6,stroke:#000;
  classDef green fill:#90EE90,stroke:#000;
  classDef orange fill:#FFA500,stroke:#000;
  classDef gray fill:#D3D3D3,stroke:#000;
  classDef purple fill:#DDA0DD,stroke:#000;
  classDef cylinder fill:#fff,stroke:#000,shape:cylinder;
  class cylinder cylinder;
```
