# ssaisriharsha/nand-backup-tool architecture

> Architecture diagram of the GitHub repository ssaisriharsha/nand-backup-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ssaisriharsha/nand-backup-tool
- Repository: https://github.com/ssaisriharsha/nand-backup-tool

## Overview

##### Project type and purpose
- This is a native C++ command‑line utility (“NAND-backup-tool”) whose sole purpose is to back up the internal NAND flash of a rooted Android device to your PC as raw `.img` files. It does not have a frontend/backend in the web sense; it’s a standalone CLI with modular source files.

##### File structure
- Top level: `README.md`, `LICENSE`, `src/`
- In `src/`:
- `Main.cpp` – orchestrates workflow (parses arguments, drives the backup)
- `helper.cpp/.hpp` – low‑level routines (e.g., running adb/fastboot commands, file I/O)
- `error_handler.cpp/.hpp` – unified error reporting and exit codes

##### Extract architectural insights from README
- External dependencies:
- ADB server (on PC)
- Magisk modules or adbd_insecure (on device) for root
- Fastboot (for restore)
- Workflow summary:
1. Gain root on device via adb
2. For each partition, run `dd` on the device over ADB shell
3. Pull raw images to PC (`.img` files in `androidBackup/`)
4. (Restore only uses Fastboot, outside the main code)

a. CLI Application (PC side)
- Main module
- Helper module
- ErrorHandler module
b. External PC Tools & Environment
- ADB client/server
- Fastboot (for restore path)
- Local filesystem (androidBackup folder)
c. Android Device
- Magisk/adb_root_enabler (or adbd_insecure)
- ADB daemon (`adbd`) running as root
- Linux shell + `dd` utility
- Device storage/NAND partitions

##### Relationships & data flows
- User invokes `nand-backup-tool` CLI → Main module
- Main calls Helper to execute ADB commands:
- `adb shell su -c "dd if=/dev/block/…"`
- Streams partition data back over ADB pipe
- Helper writes each data stream to PC filesystem (`androidBackup/*.img`)
- ErrorHandler captures any failures and reports back to Main → console
- (Optionally illustrate restore path): User calls Fastboot to flash `.img` files back to device

##### Architectural patterns & principles
- Modular separation: orchestration (Main) vs. utilities (Helper) vs. error management (ErrorHandler)
- Single process CLI, sequential workflow
- External process invocation pattern (spawning adb/fastboot)
- Idempotent storage: folder non‑overwrite check

- Clear component names (Main, Helper, ErrorHandler, ADB Server, Device adbd, Fastboot, FileSystem)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Project Documentation"
        Docs["README.md"]:::docs
        Lic["LICENSE"]:::docs
    end

    subgraph "CLI Application"
        Main["Main Module"]:::internal
        Helper["Helper Module"]:::internal
        Error["ErrorHandler Module"]:::internal
    end

    Docs -.-> Main
    Lic -.-> Main

    Main -->|"invoke helper.runAdbShell() "| Helper
    Helper -->|"on failure"| Error
    Error -->|"report error"| Main

    Main -->|"adb shell su -c 'dd if=...'"| ADBServer
    ADBServer["ADB Server"]:::external -->|"forward to adbd"| DeviceAdbd

    subgraph "Android Device"
        Magisk["Magisk/adbd_insecure"]:::external
        DeviceAdbd["adbd (root)"]:::external
        Shell["Linux shell + dd"]:::external
        Partitions["NAND Partitions"]:::storage

        Magisk --> DeviceAdbd
        DeviceAdbd --> Shell
        Shell -->|"dd stream"| Helper
    end

    Helper -->|"write .img files"| PCFS
    PCFS["androidBackup folder"]:::storage

    PCFS -->|"fastboot flash <partition> *.img"| Fastboot
    Fastboot["Fastboot"]:::external -->|"flash to bootloader"| Bootloader

    subgraph "Device Bootloader"
        Bootloader["Device Bootloader"]:::external
        Bootloader -->|"write to"| Partitions
    end

    classDef internal fill:#D6EAF8,stroke:#3498DB
    classDef external fill:#D5F5E3,stroke:#27AE60
    classDef storage fill:#FCF3CF,stroke:#F1C40F
    classDef docs fill:#E8DAEF,stroke:#8E44AD

    click Main "https://github.com/ssaisriharsha/nand-backup-tool/blob/main/src/Main.cpp"
    click Helper "https://github.com/ssaisriharsha/nand-backup-tool/blob/main/src/helper.cpp"
    click Helper "https://github.com/ssaisriharsha/nand-backup-tool/blob/main/src/helper.hpp"
    click Error "https://github.com/ssaisriharsha/nand-backup-tool/blob/main/src/error_handler.cpp"
    click Error "https://github.com/ssaisriharsha/nand-backup-tool/blob/main/src/error_handler.hpp"
    click Docs "https://github.com/ssaisriharsha/nand-backup-tool/blob/main/README.md"
    click Lic "https://github.com/ssaisriharsha/nand-backup-tool/tree/main/LICENSE"
```
