# adrienb2/qoi-encoder-go architecture

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

- Interactive diagram: https://gitdiagram.com/adrienb2/qoi-encoder-go
- Repository: https://github.com/adrienb2/qoi-encoder-go

## Overview

##### Project Type and Purpose
- This is a single-binary Command Line Interface (CLI) tool written in Go.
- Purpose: lossless image conversion between PNG and QOI formats, with optional benchmarking and batch processing.

##### File Structure
Top-level directories and files:
- cmd/
– root.go (defines the CLI root command and common flags)
– encode.go (implements the “encode” subcommand)
– decode.go (implements the “decode” subcommand)
- qoi/
– encoder.go, decoder.go (core QOI algorithm implementations)
– spec.go (format definitions)
– *_test.go (unit tests)
- png/
– png.go (PNG decoding/encoding wrapper)
- imageUtils/
– image.go (helpers for image manipulation, pixel buffers)
- utils/
– utils.go (shared utilities: file traversal, error handling, benchmarking helper)
- main.go (initializes CLI application by importing cmd package)
- Makefile, go.mod/sum (build, dependency management)
- assets/ (test images, not part of production flow)

##### README Insights
- CLI offers two commands: encode and decode.
- Flags: input/output path, batch mode, benchmark mode, help.
- Performance metrics (benchmarking) are part of the tool’s feature set.

##### Main Components & Their Relationships

A. CLI Layer
- root command (common flags parser)
- encode subcommand
- decode subcommand

B. Core Processing Layer
1. QOI Package
- qoi.encoder.Encode(inputImage) → byte stream
- qoi.decoder.Decode(byte stream) → image data
2. PNG Package
- png.Decode(file) → image data
- png.Encode(image data) → file

encode command → png.Decode → image data → qoi.encoder.Encode → QOI output
decode command → qoi.decoder.Decode → image data → png.Encode → PNG output

C. Utility Layer
- imageUtils – image buffer and pixel operations
- utils –
– FileSystem walker (batch mode)
– Benchmark timer & reporter
– Error & logging helpers

D. File System & External Interfaces
- File System (read/write)
- STDOUT/STDERR (benchmark results, error messages)
- OS Environment (flags, exit codes)

##### Architectural Patterns
- Command Pattern: each subcommand (encode/decode) encapsulates one operation.
- Layered Architecture: CLI → Core Algorithm → Utilities → I/O.
- Package Modularization:
- qoi package is self-contained for format logic.
- png package isolates PNG details.
- utils and imageUtils provide cross-cutting concerns.

##### Detailed Elements to Capture
- Flag parsing & validation module inside cmd/root.go
- Subcommand handlers in cmd/encode.go and cmd/decode.go
- QOI spec reference in qoi/spec.go (annotate as “Format Definition”)
- Unit tests in qoi/*_test.go and encoder/decoder_test.go (optionally shown as a testing overlay)
- Benchmarking hook in utils (timers around encode/decode calls)
- File traversal logic for batch mode in utils

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    User(("User")):::external
    FS(("File System")):::external
    STD(("STDOUT/STDERR")):::external
    OS(("OS Environment")):::external

    %% CLI Layer
    subgraph "CLI Frontend (cmd package)"
        root["root.go"]:::cli
        encode["encode.go"]:::cli
        decode["decode.go"]:::cli
    end
    main["main.go"]:::cli

    %% Core Processing Layer
    subgraph "Core Processing"
        subgraph "QOI Package"
            encoder["encoder.go"]:::core
            decoder["decoder.go"]:::core
            spec["spec.go"]:::core
        end
        subgraph "PNG Package"
            pngpkg["png.png"]:::core
        end
    end

    %% Utilities Layer
    subgraph "Utilities"
        imageUtils["image.go"]:::util
        utils["utils.go"]:::util
    end

    %% Test Assets
    subgraph "Test Assets"
        assets1["assets/custom_test/"]:::external
        assets2["assets/qoi_test_images/"]:::external
    end

    %% Build & Dependency Management
    subgraph "Build & Dependency"
        make["Makefile"]:::build
        mod["go.mod"]:::build
        sum["go.sum"]:::build
    end

    %% Flows and Relationships
    User -->|"invokes CLI"| main
    main -->|"initializes"| root
    root -->|"dispatches"| encode
    root -->|"dispatches"| decode
    encode -->|"Decode PNG"| pngpkg
    pngpkg -->|"ImageData"| encoder
    encoder -->|"QOI byte stream"| FS
    decode -->|"Decode QOI"| decoder
    decoder -->|"ImageData"| pngpkg
    pngpkg -->|"Write PNG"| FS

    %% Utility interactions
    root -->|"flags & logging"| utils
    encode -->|"batch & timer"| utils
    decode -->|"batch & timer"| utils
    encode -->|"pixel ops"| imageUtils
    decode -->|"pixel ops"| imageUtils
    encoder -->|"pixel ops"| imageUtils
    decoder -->|"pixel ops"| imageUtils

    %% External interfaces
    root -->|"exit codes & flags"| OS
    utils -->|"benchmark output"| STD
    root -->|"help/errors"| STD

    %% Class Definitions
    classDef external fill:#cccccc,stroke:#333;
    classDef cli fill:#87CEEB,stroke:#333;
    classDef core fill:#90EE90,stroke:#333;
    classDef util fill:#FFD700,stroke:#333;
    classDef build fill:#D3D3D3,stroke:#333;

    %% Click Events
    click root "https://github.com/adrienb2/qoi-encoder-go/blob/main/cmd/root.go"
    click encode "https://github.com/adrienb2/qoi-encoder-go/blob/main/cmd/encode.go"
    click decode "https://github.com/adrienb2/qoi-encoder-go/blob/main/cmd/decode.go"
    click main "https://github.com/adrienb2/qoi-encoder-go/blob/main/main.go"
    click encoder "https://github.com/adrienb2/qoi-encoder-go/blob/main/qoi/encoder.go"
    click decoder "https://github.com/adrienb2/qoi-encoder-go/blob/main/qoi/decoder.go"
    click spec "https://github.com/adrienb2/qoi-encoder-go/blob/main/qoi/spec.go"
    click pngpkg "https://github.com/adrienb2/qoi-encoder-go/blob/main/png/png.go"
    click imageUtils "https://github.com/adrienb2/qoi-encoder-go/blob/main/imageUtils/image.go"
    click utils "https://github.com/adrienb2/qoi-encoder-go/blob/main/utils/utils.go"
    click assets1 "https://github.com/adrienb2/qoi-encoder-go/tree/main/assets/custom_test/"
    click assets2 "https://github.com/adrienb2/qoi-encoder-go/tree/main/assets/qoi_test_images/"
    click make "https://github.com/adrienb2/qoi-encoder-go/tree/main/Makefile"
    click mod "https://github.com/adrienb2/qoi-encoder-go/blob/main/go.mod"
    click sum "https://github.com/adrienb2/qoi-encoder-go/blob/main/go.sum"
```
