# davidgfnet/superfw-nds-flasher-tool architecture

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

- Interactive diagram: https://gitdiagram.com/davidgfnet/superfw-nds-flasher-tool
- Repository: https://github.com/davidgfnet/superfw-nds-flasher-tool

## Overview

##### Project Type and Purpose
- This is a small command‐line utility written in C for Nintendo DS (NDS) “Supercard” devices. Its sole purpose is to dump (read out) and flash (write) the firmware on a Supercard cartridge, and verify integrity via SHA‑256.

##### File Structure Analysis
- Top‐level files:
- .github/workflows/build-release.yml – CI pipeline for building and releasing binaries
- Makefile – build script invoking gcc on source files
- README.md – high‐level description
- Source directory:
- main.c – entry point, CLI parsing, high‐level orchestration
- sha256.c – standalone implementation of SHA‑256 digest

##### Key Components
a. CLI Front‑end
- Parses user commands (“dump”, “flash”)
- Validates arguments (e.g. input/output file paths)
b. Command Dispatcher
- Determines whether to invoke DumpModule or FlashModule
c. Dump/Flash Module
- Implements low‐level I/O over a physical interface (likely USB) to the NDS cartridge
- Reads raw firmware data into memory or writes provided firmware blobs
d. SHA‑256 Module
- Computes cryptographic hash of firmware images for integrity checks
- Called post‐dump (to fingerprint) or pre‐flash (to verify before writing)
e. Build & Release Pipeline
- Makefile for local builds
- GitHub Actions workflow for CI builds, packaging, and GitHub Releases

##### Relationships and Data Flows
- User invokes the CLI tool on the host machine
→ CLI Front‑end parses input
→ Dispatcher routes to DumpModule or FlashModule
→ DumpModule communicates over USB to the Supercard hardware
→ Retrieves raw firmware bytes
→ Passes data to SHA‑256 Module
→ Outputs checksum to user or log
→ FlashModule reads firmware file from host
→ Validates with SHA‑256 Module (optional)
→ Sends bytes to device over USB
- Build pipeline compiles main.c + sha256.c → produces binary artifact → GitHub Actions bundles release

##### Architectural Patterns and Design Principles
- Layered design:
- Presentation layer: CLI parsing
- Service layer: Dump/Flash logic
- Utility layer: SHA‑256 calculation
- Single executable, static linking of modules
- Clear separation of concerns: no cross‐cutting between cryptography and I/O code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Front-end\n(Parser & Dispatcher)"]:::user
    end

    %% Service Layer
    subgraph "Service Layer"
        Dump["DumpModule"]:::core
        Flash["FlashModule"]:::core
    end

    %% Utility Layer
    subgraph "Utility Layer"
        SHA["SHA-256 Module"]:::util
    end

    %% External Systems and Files
    subgraph "External Interfaces"
        User["User"]:::user
        HW["Supercard Hardware\n(USB)"]:::external
        File["Firmware File\n(.bin)"]:::external
    end

    %% Build & Release
    subgraph "Build & Release Pipeline"
        BuildLocal["Makefile"]:::external
        CI["GitHub Actions\n(build-release.yml)"]:::external
        Binary["Binary Artifact"]:::external
        DOC["README.md"]:::external
    end

    %% Data/control flows
    User -->|invokes| CLI
    CLI -->|routes to| Dump
    CLI -->|routes to| Flash

    Dump -->|reads/writes raw bytes over USB| HW
    HW -->|raw firmware bytes| Dump
    Dump -->|passes data| SHA
    SHA -->|checksum| CLI

    Flash -->|reads .bin| File
    Flash -->|validates via| SHA
    Flash -->|writes bytes over USB| HW

    %% Build flows
    BuildLocal -->|compiles source| Binary
    CI -->|builds & packages| Binary
    DOC -.->|describes| CLI

    %% Click events
    click CLI "https://github.com/davidgfnet/superfw-nds-flasher-tool/blob/master/source/main.c"
    click Dump "https://github.com/davidgfnet/superfw-nds-flasher-tool/blob/master/source/main.c"
    click Flash "https://github.com/davidgfnet/superfw-nds-flasher-tool/blob/master/source/main.c"
    click SHA "https://github.com/davidgfnet/superfw-nds-flasher-tool/blob/master/source/sha256.c"
    click BuildLocal "https://github.com/davidgfnet/superfw-nds-flasher-tool/tree/master/Makefile"
    click CI "https://github.com/davidgfnet/superfw-nds-flasher-tool/blob/master/.github/workflows/build-release.yml"
    click DOC "https://github.com/davidgfnet/superfw-nds-flasher-tool/blob/master/README.md"

    %% Styles
    classDef user fill:#9be7ff,stroke:#0288d1;
    classDef core fill:#a5d6a7,stroke:#2e7d32;
    classDef util fill:#fff59d,stroke:#f9a825;
    classDef external fill:#e0e0e0,stroke:#9e9e9e;
```
