# aditya-bachhav/adi-codec architecture

> Architecture diagram of the GitHub repository aditya-bachhav/adi-codec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditya-bachhav/adi-codec
- Repository: https://github.com/aditya-bachhav/adi-codec

## Overview

1. **What this repository is, in practice**
   - The checked-in code is a **small Python image-encoding prototype** centered around a single script, `encoder.py`.
   - Although the README describes a larger “ADI v0.1” system with training, decoding, and a demo, the file tree here does **not** contain that full multi-module stack.

2. **Main runtime boundary**
   - The only obvious executable entry point is `encoder.py`.
   - This script appears to be responsible for taking an image from `source_img/` and producing a compressed `.adi` artifact in `outputs/`.

3. **Primary data flow**
   - Input images live in `source_img/`.
   - The encoder processes them and writes binary output to `outputs/`, with `outputs/ADI_IMG.adi` serving as a sample result.
   - That makes the repository mostly a **one-way encode pipeline** rather than a full codec system in this tree.

4. **Artifacts and sample assets**
   - `outputs/ADI_IMG.adi` is the key generated artifact and is likely the format this repo is demonstrating.
   - `assets/` contains README imagery such as the hero graphic; these are documentation/marketing assets, not runtime dependencies.
   - `.vscode/` is editor configuration only and not part of the product architecture.

5. **Dependency boundary**
   - `requirenment.txt` is the dependency manifest, but it is misspelled; that suggests a lightweight, manual Python setup rather than a packaged library/app.
   - The runtime is therefore almost certainly **local Python execution**, not a service, daemon, or deployed backend.

6. **Codec architecture implied by the README**
   - The README describes a more elaborate codec architecture: training a codebook, encoding images into tokenized instructions, and decoding `.adi` files back to images.
   - In architectural terms, that implies three conceptual subsystems:
     - **Codebook/training**: learn tokens from images
     - **Encoder**: convert image blocks/features into `.adi`
     - **Decoder**: reconstruct image from `.adi`
   - However, only the encoder-side artifact is visible in this repo tree.

7. **Likely missing subsystems relative to the README**
   - The README mentions downloader, trainer, codec, and a Gradio demo, but none of those folders/files appear in the tree.
   - So for an accurate diagram, treat those as **described-but-not-present** components, or as future/aspirational modules rather than current implementation.

8. **Format and storage boundary**
   - The `.adi` file is the repository’s core output format and serves as the persistence boundary between encoding and any later decoding step.
   - The sample output in `outputs/` indicates the format is intended to be portable and inspectable as a generated artifact.

9. **No obvious external infrastructure**
   - There is no evidence here of databases, queues, cloud services, or web APIs.
   - The architecture is therefore best drawn as a **single-process local toolchain** with file-based I/O.

10. **How to diagram it**
   - Draw `source_img/` as the input source, `encoder.py` as the central processing node, and `outputs/*.adi` as the emitted binary artifact.
   - Show `assets/` and the README as documentation/supporting material off to the side.
   - If you include the broader README vision, mark training/codebook generation and decoding as **conceptual modules not present in this checkout**.

11. **Overall architectural summary**
   - This repository is currently closest to a **prototype image compressor/encoder** with a file-based workflow.
   - The core boundary is simple: **image files in, `.adi` files out**, implemented in Python, with the richer “codec platform” described in the README not fully reflected in the repository contents.

Main entry points: [`encoder.py`](https://github.com/aditya-bachhav/adi-codec/blob/main/encoder.py) (encoder.py), [`source_img`](https://github.com/aditya-bachhav/adi-codec/tree/main/source_img) (source_img), [`requirenment.txt`](https://github.com/aditya-bachhav/adi-codec/blob/main/requirenment.txt) (requirenment.txt), [`outputs`](https://github.com/aditya-bachhav/adi-codec/tree/main/outputs) (outputs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_encoder_py["encoder.py<br/>entrypoint<br/>[encoder.py]"]
  node_source_img[("source_img<br/>input dir")]
  node_outputs_dir[("outputs<br/>artifact dir")]
  node_adi_sample["ADI_IMG.adi<br/>binary artifact<br/>[ADI_IMG.adi]"]
end

subgraph group_support["Support"]
  node_readme_md["Readme.md<br/>docs<br/>[Readme.md]"]
  node_requirements_txt["requirenment.txt<br/>deps manifest<br/>[requirenment.txt]"]
  node_assets_dir["assets"]
end

node_source_img -->|"images in"| node_encoder_py
node_encoder_py -->|"writes"| node_outputs_dir
node_encoder_py -->|"produces"| node_adi_sample
node_requirements_txt -.->|"deps"| node_encoder_py

click node_encoder_py "https://github.com/aditya-bachhav/adi-codec/blob/main/encoder.py"
click node_source_img "https://github.com/aditya-bachhav/adi-codec/tree/main/source_img"
click node_outputs_dir "https://github.com/aditya-bachhav/adi-codec/tree/main/outputs"
click node_adi_sample "https://github.com/aditya-bachhav/adi-codec/blob/main/outputs/ADI_IMG.adi"
click node_readme_md "https://github.com/aditya-bachhav/adi-codec/blob/main/Readme.md"
click node_requirements_txt "https://github.com/aditya-bachhav/adi-codec/blob/main/requirenment.txt"
click node_assets_dir "https://github.com/aditya-bachhav/adi-codec/tree/main/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_encoder_py,node_source_img,node_outputs_dir,node_adi_sample toneBlue
class node_readme_md,node_requirements_txt,node_assets_dir toneAmber
```

## Components

### Runtime

Local image encoding pipeline

- [encoder.py](https://github.com/aditya-bachhav/adi-codec/blob/main/encoder.py): entrypoint · Main Python encoder script · `encoder.py`
- [source_img](https://github.com/aditya-bachhav/adi-codec/tree/main/source_img): input dir · Source images for encoding · `source_img`
- [outputs](https://github.com/aditya-bachhav/adi-codec/tree/main/outputs): artifact dir · Destination for generated .adi files · `outputs`
- [ADI_IMG.adi](https://github.com/aditya-bachhav/adi-codec/blob/main/outputs/ADI_IMG.adi): binary artifact · Sample encoded ADI output · `outputs/ADI_IMG.adi`

### Support

Docs, assets, and setup files

- [Readme.md](https://github.com/aditya-bachhav/adi-codec/blob/main/Readme.md): docs · Repository overview and codec vision · `Readme.md`
- [requirenment.txt](https://github.com/aditya-bachhav/adi-codec/blob/main/requirenment.txt): deps manifest · Python dependency list · `requirenment.txt`
- [assets](https://github.com/aditya-bachhav/adi-codec/tree/main/assets): docs assets · README imagery and supporting media · `assets`

## Connections

- source_img → encoder.py: images in · Encoder reads source images from this folder
- encoder.py → outputs: writes · Encoded artifacts are emitted here
- encoder.py → ADI_IMG.adi: produces · Sample ADI file generated by the encoder
- requirenment.txt → encoder.py: deps · Python execution environment for the script
