# cefqrn/jpeg-decoder architecture

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

- Interactive diagram: https://gitdiagram.com/cefqrn/jpeg-decoder
- Repository: https://github.com/cefqrn/jpeg-decoder

## Overview

##### Project type and purpose
- This is an open-source, command-line JPEG decoder library/tool written in C.

##### File structure
Top-level files and dirs:
- src/ – all C sources and headers, each implementing one logical piece of the decoder
– parsing.(c|h): reads JPEG markers, headers, quant tables, Huffman tables
– bitstream.(c|h): buffered bit-level I/O from compressed data segments
– hufftree.(c|h): builds/traverses Huffman decode trees
– decoding.(c|h): performs inverse DCT, dequantization, MCU assembly
– jpeg.(c|h): top-level orchestration of parse → decode → output
– macros.h: shared constants and helper macros
– test.c: CLI entry point (./bin/test)
- examples/: sample JPEGs for manual testing
- Makefile, README.md, LICENSE

##### README for additional insights
- Only “Baseline DCT” JPEG is supported.
- Outputs to terminal via ANSI 24-bit escape codes.
- No external libraries beyond standard C.

##### Main components & interactions
1. CLI Interface (test.c)
2. JPEG Orchestrator (jpeg.c/h)
3. Parser Module (parsing.c/h)
4. Bitstream Module (bitstream.c/h)
5. Huffman Module (hufftree.c/h)
6. Decoder Module (decoding.c/h)
7. Image Module (image.c/h)
8. Terminal Renderer (ANSI escape sequences)
9. File System (input JPEG file)
– User invokes CLI → reads JPEG file from FS
– File data → Parser extracts markers, headers, tables
– Compressed segment bytes → Bitstream → feeds bits → Huffman tree → decoded coefficients
– Coefficients → Decoder → dequantize & iDCT → raw pixels
– Raw pixels → Image Module → map to RGB blocks
– RGB blocks → ANSI sequences → stdout → Terminal
C. External/optional elements
– Example images folder (not in pipeline)
– Makefile invoked to build binaries
– Potential extension: add chroma subsampling support or extra JPEG features

##### Important patterns & principles
– Pipeline architecture: each module has a single responsibility and passes data “downstream.”
– Separation of concerns: parsing vs bit-level I/O vs entropy decoding vs pixel processing.
– Strict layering: upper layers never manipulate raw bit buffers directly, they rely on the bitstream API.
– Header-only definitions (macros.h) to share constants across modules without circular includes.

##### Tools & output
- Export as SVG/PNG to include in the repo or documentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    FileSystem["File System\n(JPEG file)"]:::external
    Terminal["Terminal\n(stdout)"]:::external

    %% Orchestration Layer
    subgraph "Orchestration" 
        CLI["CLI Interface\ntest.c"]:::orchestration
        Orchestrator["JPEG Orchestrator\njpeg.c/h"]:::orchestration
    end

    %% Core Decoder Modules
    subgraph "Core Decoder Modules"
        Parser["Parser Module\nparsing.c/h"]:::core
        Bitstream["Bitstream Module\nbitstream.c/h"]:::core
        Huffman["Huffman Module\nhufftree.c/h"]:::core
        Decoder["Decoder Module\ndecoding.c/h"]:::core
    end

    %% Image & Rendering
    ImageModule["Image Module\nimage.c/h"]:::artifact
    TerminalRenderer["Terminal Renderer\nANSI sequences"]:::artifact

    %% Shared & External Artifacts
    Macros["Shared Constants & Macros\nmacros.h"]:::artifact
    ExampleInputs["Example JPEG Inputs\nexamples/"]:::external
    BuildSystem["Build System\nMakefile"]:::external
    Documentation["Project Documentation\nREADME.md"]:::external
    License["License Information\nLICENSE"]:::external

    %% Pipeline Flow
    FileSystem -->|"bytes"| Parser
    Parser -->|"bytes"| Bitstream
    Bitstream -->|"bits"| Huffman
    Huffman -->|"coefficients"| Decoder
    Decoder -->|"raw pixels"| ImageModule
    ImageModule -->|"RGB blocks"| TerminalRenderer
    TerminalRenderer -->|"ANSI sequences"| Terminal

    %% Orchestration Flow
    CLI -->|runs decode pipeline| Orchestrator
    Orchestrator -->|orchestrates| Parser

    %% Support Flows
    ExampleInputs -.->|manual test| CLI
    BuildSystem -.->|builds| CLI
    BuildSystem -.->|builds| Orchestrator

    %% Click Events
    click CLI "https://github.com/cefqrn/jpeg-decoder/blob/main/src/test.c"
    click Orchestrator "https://github.com/cefqrn/jpeg-decoder/blob/main/src/jpeg.c"
    click Parser "https://github.com/cefqrn/jpeg-decoder/blob/main/src/parsing.c"
    click Bitstream "https://github.com/cefqrn/jpeg-decoder/blob/main/src/bitstream.c"
    click Huffman "https://github.com/cefqrn/jpeg-decoder/blob/main/src/hufftree.c"
    click Decoder "https://github.com/cefqrn/jpeg-decoder/blob/main/src/decoding.c"
    click ImageModule "https://github.com/cefqrn/jpeg-decoder/blob/main/src/image.c"
    click Macros "https://github.com/cefqrn/jpeg-decoder/blob/main/src/macros.h"
    click ExampleInputs "https://github.com/cefqrn/jpeg-decoder/tree/main/examples/no_subsampling"
    click BuildSystem "https://github.com/cefqrn/jpeg-decoder/tree/main/Makefile"
    click Documentation "https://github.com/cefqrn/jpeg-decoder/blob/main/README.md"
    click License "https://github.com/cefqrn/jpeg-decoder/tree/main/LICENSE"

    %% Styling
    classDef orchestration fill:#9f6,stroke:#333,color:#000
    classDef core fill:#6cf,stroke:#333,color:#000
    classDef external fill:#ccc,stroke:#333,color:#000
    classDef artifact fill:#ffb,stroke:#333,color:#000

    %% Legend
    subgraph Legend
        O[Orchestration Layer]:::orchestration
        C[Core Modules]:::core
        E[External Systems]:::external
        A[Artifacts & Data]:::artifact
    end
```
