# rishi-269/pixelhide architecture

> Architecture diagram of the GitHub repository rishi-269/pixelhide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rishi-269/pixelhide
- Repository: https://github.com/rishi-269/pixelhide

## Overview

1. Pixel Hide is a single native C++17 command-line binary, not a service or library stack. The architecture is centered on one executable that orchestrates steganography and optional encryption over local files.

2. The top-level entry point is `main.cpp`. It is the CLI boundary: parses modes like help, key generation, insert, and retrieve, then dispatches into the lower-level image, file, and crypto routines.

3. The core steganography subsystem lives in `image.cpp/.hpp`. This is where image data is loaded, modified, and written back out. The README makes clear the hidden-data mechanism is LSB-based, so the image layer is responsible for mapping payload bits into pixel channels and reconstructing them during extraction.

4. Image I/O is built on vendored `stb_image.h` and `stb_image_write.h` under `stb/`. These headers form the format-handling boundary for reading common inputs like PNG/JPG/BMP and writing only lossless outputs such as PNG/BMP, which matters because lossy output would destroy embedded bits.

5. Payload and key handling are separated into `file.cpp/.hpp`. This module likely owns file reads/writes, payload size handling, and key file generation/storage, keeping file-system concerns out of the image codec path.

6. Optional encryption is handled by vendored `tiny-aes/aes.c/.h`. The README states AES in CTR mode, so the data flow is: plaintext file content is optionally encrypted before embedding, and decrypted after extraction if a key is provided.

7. The main runtime flow for insertion is: read input file content, optionally encrypt it, serialize metadata plus payload, embed the resulting bitstream into image pixels, then write a new steganographic image. The output image is the primary artifact produced by the tool.

8. The retrieval flow is the inverse: load the stego image, extract the hidden bitstream from pixel LSBs, parse out the embedded payload, and optionally decrypt it using the provided key. The final output is the recovered file bytes written back to disk.

9. The important architectural boundary is between “carrier processing” and “payload processing.” Image manipulation is isolated from file/encryption logic, which keeps the stego algorithm independent from format-specific details and from cryptographic details.

10. This repo has no network layer, no database, and no background workers. The entire system is local, file-driven, and deterministic, with external dependencies limited to vendored image codecs and AES implementation code.

11. For an architecture diagram, the key nodes are: CLI entry point, file/payload manager, optional AES-CTR encrypt/decrypt module, LSB embedding/extraction engine, and image codec layer. The main arrows are from CLI to processing modules, then from input files/images into the pipeline, and finally to output image/file artifacts.

Main entry points: [`image.cpp`](https://github.com/rishi-269/pixelhide/blob/main/image.cpp) (image.cpp), [`file.cpp`](https://github.com/rishi-269/pixelhide/blob/main/file.cpp) (file.cpp), [`main.cpp`](https://github.com/rishi-269/pixelhide/blob/main/main.cpp) (main.cpp), [`tiny-aes/aes.c`](https://github.com/rishi-269/pixelhide/blob/main/tiny-aes/aes.c) (AES CTR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main_cpp["main.cpp<br/>cli entry<br/>[main.cpp]"]
end

subgraph group_payload["Payload"]
  node_file_cpp["file.cpp<br/>payload I/O<br/>[file.cpp]"]
  node_input_file["Input file<br/>source artifact"]
  node_key_file["Key file<br/>key artifact"]
  node_hidden_stream["Hidden stream<br/>bitstream"]
  node_recovered_file["Recovered file<br/>output artifact"]
end

subgraph group_carrier["Carrier"]
  node_image_cpp["image.cpp<br/>stego engine<br/>[image.cpp]"]
  node_carrier_image["Carrier image<br/>input artifact"]
  node_stego_image["Stego image<br/>output artifact"]
end

subgraph group_deps["Vendored deps"]
  node_stb_image["stb_image<br/>image read<br/>[stb_image.h]"]
  node_stb_write["stb_write<br/>image write<br/>[stb_image_write.h]"]
  node_aes_c["AES CTR<br/>crypto<br/>[aes.c]"]
end

node_main_cpp -->|"dispatches"| node_file_cpp
node_main_cpp -->|"dispatches"| node_image_cpp
node_main_cpp -->|"uses"| node_aes_c
node_file_cpp -->|"reads"| node_input_file
node_file_cpp -->|"creates/reads"| node_key_file
node_file_cpp -->|"serializes"| node_hidden_stream
node_aes_c -->|"encrypts/decrypts"| node_hidden_stream
node_image_cpp -->|"loads"| node_carrier_image
node_image_cpp -->|"embeds/extracts"| node_hidden_stream
node_image_cpp -->|"writes"| node_stego_image
node_image_cpp -->|"outputs"| node_recovered_file
node_image_cpp -->|"decodes with"| node_stb_image
node_image_cpp -->|"encodes with"| node_stb_write
node_hidden_stream -->|"becomes"| node_stego_image
node_hidden_stream -->|"restores"| node_recovered_file

click node_main_cpp "https://github.com/rishi-269/pixelhide/blob/main/main.cpp"
click node_file_cpp "https://github.com/rishi-269/pixelhide/blob/main/file.cpp"
click node_image_cpp "https://github.com/rishi-269/pixelhide/blob/main/image.cpp"
click node_stb_image "https://github.com/rishi-269/pixelhide/blob/main/stb/stb_image.h"
click node_stb_write "https://github.com/rishi-269/pixelhide/blob/main/stb/stb_image_write.h"
click node_aes_c "https://github.com/rishi-269/pixelhide/blob/main/tiny-aes/aes.c"

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_main_cpp toneBlue
class node_file_cpp,node_input_file,node_key_file,node_hidden_stream,node_recovered_file toneAmber
class node_image_cpp,node_carrier_image,node_stego_image toneMint
class node_stb_image,node_stb_write,node_aes_c toneRose
```

## Components

### CLI

Command-line entry and orchestration

- [main.cpp](https://github.com/rishi-269/pixelhide/blob/main/main.cpp): cli entry · Parses modes and dispatches insert/retrieve/key flows · `main.cpp`

### Payload

File handling and optional encryption

- [file.cpp](https://github.com/rishi-269/pixelhide/blob/main/file.cpp): payload I/O · Reads payload bytes, manages keys, and writes recovered output · `file.cpp`
- **Input file**: source artifact · Plaintext payload read from disk before embedding
- **Key file**: key artifact · Generated or supplied key material for encryption
- **Hidden stream**: bitstream · Serialized metadata and payload bytes prepared for LSB embedding
- **Recovered file**: output artifact · Extracted payload bytes written back to disk

### Carrier

Image loading, bit embedding, and writing

- [image.cpp](https://github.com/rishi-269/pixelhide/blob/main/image.cpp): stego engine · Embeds and extracts hidden data in image pixels · `image.cpp`
- **Carrier image**: input artifact · Cover image loaded for steganographic modification
- **Stego image**: output artifact · Modified image written with embedded payload bits

### Vendored deps

Embedded third-party codec and crypto code

- [stb_image](https://github.com/rishi-269/pixelhide/blob/main/stb/stb_image.h): image read · Vendored decoder for loading carrier images · `stb/stb_image.h`
- [stb_write](https://github.com/rishi-269/pixelhide/blob/main/stb/stb_image_write.h): image write · Vendored encoder for writing output images · `stb/stb_image_write.h`
- [AES CTR](https://github.com/rishi-269/pixelhide/blob/main/tiny-aes/aes.c): crypto · Vendored AES implementation used for optional encryption · `tiny-aes/aes.c`

## Connections

- main.cpp → file.cpp: dispatches · Routes CLI commands to file and key operations
- main.cpp → image.cpp: dispatches · Routes insert and retrieve actions into stego processing
- main.cpp → AES CTR: uses · Wires optional encryption into the command flow
- file.cpp → Input file: reads · Loads payload bytes from local files
- file.cpp → Key file: creates/reads · Generates or opens key material
- file.cpp → Hidden stream: serializes · Packages payload and metadata for embedding
- AES CTR → Hidden stream: encrypts/decrypts · Transforms payload bytes when a key is provided
- image.cpp → Carrier image: loads · Reads the cover image into memory
- image.cpp → Hidden stream: embeds/extracts · Maps payload bits into or out of pixel channels
- image.cpp → Stego image: writes · Emits the modified image after insertion
- image.cpp → Recovered file: outputs · Passes extracted bytes to file writing logic
- image.cpp → stb_image: decodes with · Uses vendored loader for input formats
- image.cpp → stb_write: encodes with · Uses vendored writer for output formats
- Hidden stream → Stego image: becomes · Embedded data is persisted inside the carrier output
- Hidden stream → Recovered file: restores · Extracted stream is converted back into file bytes
