# prtmsh/steganography-py architecture

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

- Interactive diagram: https://gitdiagram.com/prtmsh/steganography-py
- Repository: https://github.com/prtmsh/steganography-py

## Overview

##### Project Type and Purpose
- This is a standalone Python command-line tool (an open-source steganography utility) for embedding and extracting invisible text watermarks in images using a border-hash based LSB scheme.

##### High-Level Architecture Overview
- The system can be broken down into four main domains:
a. Command-Line Interface (CLI) Layer
b. Core Watermarking Engine
c. Image I/O & Pre/Post-Processing
d. External Dependencies

##### Main Components
A. CLI Layer (src/main.py)
- Argument parser (mode, input path, output path, message)
- Dispatcher: invokes either Embed or Extract flow in the Core Engine

B. Core Watermarking Engine (src/watermark.py)
1. BorderExtractor & Hasher
- Reads outer 1-pixel border → computes SHA-256 hash
2. PRNG Seeder
- Uses hash as seed → generates reproducible pseudo-random interior pixel positions
3. Encoder (Embedding Flow)
- Prepend 16-bit length header to UTF-8 bitstream
- Embed bits into LSB of Blue channel of selected pixels
4. Decoder (Extraction Flow)
- Extract first 16 bits → recover message length
- Extract remaining bits → reconstruct UTF-8 text
5. Utility Functions
- Bit manipulation, header assembly/disassembly

C. Image I/O & Format Handling
- Uses Pillow/OpenCV/NumPy (from requirements.txt) to:
- Load input image
- Access and modify pixel buffers
- Save output as PNG (auto-convert other formats)

D. External Libraries
- OpenCV, NumPy, Pillow for image processing
- Python’s built-in hashlib for SHA-256
- Python’s built-in argparse for CLI

##### Component Interactions and Data Flow
1. User invokes CLI → src/main.py parses args
2. CLI calls watermark.Engine.embed() or .extract()
3. Engine loads image (ImageLoader) → passes pixel array to BorderExtractor
4. BorderExtractor → HashCalculator → seed to PRNG
5. PRNG → PixelSelector → either Encoder or Decoder
6. Encoder modifies pixel array → passed back to ImageSaver → writes watermarked PNG
7. Decoder reads pixel array → extracts bits → reconstructs text → prints result

##### Architectural Patterns & Principles
- Single-responsibility modules: each subcomponent (border hashing, PRNG, encoding, decoding) encapsulates one task
- Clear separation between CLI, core engine, and I/O concerns
- Deterministic design: border hash → repeatable PRNG sequence ensures reversible watermarking

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["CLI Layer"]:::cli
    click CLI "https://github.com/prtmsh/steganography-py/blob/main/src/main.py"

    %% Core Engine
    subgraph "Core Watermarking Engine"
        direction TB
        BorderExtractor["BorderExtractor"]:::core
        HashCalculator["HashCalculator"]:::core
        PRNG["PRNG Seeder"]:::core
        Encoder["LSB Encoder"]:::core
        Decoder["LSB Decoder"]:::core
        Utils["Utility Functions"]:::core
        click BorderExtractor "https://github.com/prtmsh/steganography-py/blob/main/src/watermark.py"
        click HashCalculator "https://github.com/prtmsh/steganography-py/blob/main/src/watermark.py"
        click PRNG "https://github.com/prtmsh/steganography-py/blob/main/src/watermark.py"
        click Encoder "https://github.com/prtmsh/steganography-py/blob/main/src/watermark.py"
        click Decoder "https://github.com/prtmsh/steganography-py/blob/main/src/watermark.py"
        click Utils "https://github.com/prtmsh/steganography-py/blob/main/src/watermark.py"
    end

    %% I/O Layer
    subgraph "Image I/O & Format Handling"
        direction TB
        InputStore[(Input Image Store)]:::io
        ImageLoader["ImageLoader"]:::io
        PixelBuffer["Pixel Buffer"]:::io
        ImageSaver["ImageSaver"]:::io
        OutputStore[(Output Image Store)]:::io
        click ImageLoader "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
        click ImageSaver "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
    end

    %% Data Streams
    Bitstream[/Bitstream/]:::core
    MessageStore[(Extracted Message)]:::io

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        OpenCV["OpenCV"]:::ext
        NumPy["NumPy"]:::ext
        Pillow["Pillow"]:::ext
        Hashlib["hashlib"]:::ext
        Argparse["argparse"]:::ext
        click OpenCV "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
        click NumPy "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
        click Pillow "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
        click Hashlib "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
        click Argparse "https://github.com/prtmsh/steganography-py/blob/main/requirements.txt"
    end

    %% Connections
    CLI -->|"invoke embed/extract"| BorderExtractor
    CLI --> Argparse

    InputStore -->|"load image"| ImageLoader
    ImageLoader -->|"pixel buffer"| PixelBuffer
    PixelBuffer --> BorderExtractor

    BorderExtractor -->|"SHA-256 hash"| HashCalculator
    HashCalculator -->|"hash"| PRNG

    PRNG -->|"pixel indices"| Encoder
    PRNG -->|"pixel indices"| Decoder

    Encoder -->|"modified pixel buffer"| ImageSaver
    ImageSaver -->|"writes PNG"| OutputStore

    Decoder -->|"bitstreams"| Bitstream
    Bitstream --> Utils
    Utils --> Decoder
    Decoder -->|"text output"| MessageStore

    ImageLoader --> OpenCV
    ImageLoader --> Pillow
    ImageLoader --> NumPy
    HashCalculator --> Hashlib

    %% Styles
    classDef cli fill:#D0E6FA,stroke:#0366D6,color:#000
    classDef core fill:#E6F4EA,stroke:#22863A,color:#000
    classDef io fill:#FFF4E6,stroke:#D69F37,color:#000
    classDef ext fill:#EDEDED,stroke:#6A737D,color:#000
```
