# iitzfarooq/parallelpixels architecture

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

- Interactive diagram: https://gitdiagram.com/iitzfarooq/parallelpixels
- Repository: https://github.com/iitzfarooq/parallelpixels

## Overview

##### Project type and purpose
- This is a native C-based, multi-stage image‐processing pipeline.
- It reads images from disk, chunks them in a producer–consumer setup, applies filters, and reconstructs the images back to disk.

##### File structure
- Top‐level modules:
- pipeline/chunking – code to monitor a directory, chunk images, push into buffer #1
- pipeline/filter   – code to pull chunks from buffer #1, apply filters, push into buffer #2
- pipeline/reconstruction – code to pull from buffer #2, reassemble images, write to disk
- shared/           – common data structures (dynamic arrays, lists, hash tables), image I/O (stb_image, stb_image_write), thread pool
- vendors/xxHash    – third-party hashing library (used for chunk identifiers or data integrity)
- Synchronization primitives (mutexes, semaphores) live in the shared code and are used by each stage
- main.c and CMakeLists.txt glue everything together

##### Key insights from the README
- Three logical stages (loader & chunker, filter, reconstruction) connected via two shared‐memory queues
- Each stage may use thread pooling, per-chunk threads, and must synchronize with mutexes/semaphores
- The project is a demonstration of workload distribution across threads and stages

##### Detail
- Use of semaphores/mutexes on buffer boundaries
- Build/orchestration: main.c initializing each pipeline stage and clean.sh / CMakeLists for deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestrator
    subgraph "Orchestrator"
        Orch["main.c / CMakeLists.txt / clean.sh"]:::orchestrator
    end

    %% External Source and Sink
    Disk["Input Directory"]:::external
    DiskOut["Output Directory"]:::external

    %% Processing Stages
    Chunker["Image Loader & Chunker\n(thread-pool, mutexes)"]:::proc
    Filter["Filter Service\n(thread-pool, mutexes)"]:::proc
    Reconstructor["Reconstruction Service\n(thread-pool, mutexes)"]:::proc

    %% Buffers
    Buffer1["Buffer #1\n(Producer–Consumer Queue)"]:::buffer
    Buffer2["Buffer #2\n(Producer–Consumer Queue)"]:::buffer

    %% Shared Libraries and External Vendor
    Shared["Shared Library\n(data structures, image I/O,\nthread-pool, sync)"]:::shared
    xxHash["xxHash Library"]:::vendor

    %% Flow
    Orch -->|"initialize stages"| Disk
    Disk -->|"read images"| Chunker
    Chunker -->|"chunk & enqueue"| Buffer1
    Buffer1 -->|"dequeue"| Filter
    Filter -->|"apply filters & enqueue"| Buffer2
    Buffer2 -->|"dequeue"| Reconstructor
    Reconstructor -->|"reassemble & write"| DiskOut
    Orch -.->|"teardown"| DiskOut

    %% Dependencies
    Chunker --> Shared
    Filter --> Shared
    Reconstructor --> Shared
    Filter --> xxHash

    %% Click Events
    click Orch "https://github.com/iitzfarooq/parallelpixels/blob/main/main.c"
    click Chunker "https://github.com/iitzfarooq/parallelpixels/tree/main/pipeline/chunking/"
    click Buffer1 "https://github.com/iitzfarooq/parallelpixels/blob/main/pipeline/chunking/include/image_queue.h"
    click Buffer1 "https://github.com/iitzfarooq/parallelpixels/blob/main/pipeline/chunking/src/image_queue.c"
    click Filter "https://github.com/iitzfarooq/parallelpixels/tree/main/pipeline/filter/"
    click Buffer2 "https://github.com/iitzfarooq/parallelpixels/blob/main/pipeline/chunking/include/image_queue.h"
    click Buffer2 "https://github.com/iitzfarooq/parallelpixels/blob/main/pipeline/chunking/src/image_queue.c"
    click Reconstructor "https://github.com/iitzfarooq/parallelpixels/tree/main/pipeline/reconstruction/"
    click Shared "https://github.com/iitzfarooq/parallelpixels/blob/main/shared/darray.h"
    click xxHash "https://github.com/iitzfarooq/parallelpixels/tree/main/vendors/xxHash/"

    %% Styling
    classDef proc fill:#cce5ff,stroke:#004085,color:#004085;
    classDef buffer fill:#d4edda,stroke:#155724,color:#155724;
    classDef shared fill:#fff3cd,stroke:#856404,color:#856404;
    classDef vendor fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f0f0f0,stroke:#999999,color:#333333;
    classDef orchestrator fill:#f8d7da,stroke:#721c24,color:#721c24;
```
