# mr-devakumar/bulk-image-handler architecture

> Architecture diagram of the GitHub repository mr-devakumar/bulk-image-handler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-devakumar/bulk-image-handler
- Repository: https://github.com/mr-devakumar/bulk-image-handler

## Overview

1. **Overall shape**
   - This is a single-purpose Python desktop/CLI utility for batch image processing.
   - The repository is small and centered around one core processing engine, with two front ends: a command-line entry point and a GUI entry point.

2. **Core processing subsystem**
   - `image_processor.py` is the heart of the system.
   - It likely owns the batch workflow: loading images, resizing them, converting formats, writing outputs, handling errors, and tracking per-file results.
   - The README indicates it also handles memory-conscious batch execution and professional logging.

3. **Command-line interface boundary**
   - `main.py` is the CLI entry point.
   - Its role is to parse arguments, validate user input, load configuration, invoke the image-processing core, and optionally trigger reporting or overwrite behavior.
   - This is the automation-friendly path for scripted or repeatable use.

4. **GUI boundary**
   - `gui_app.py` is a separate user interface front end.
   - It provides the same underlying processing capabilities through a non-technical workflow, likely with form inputs for source folder, destination folder, resize settings, and output format.
   - The GUI should be viewed as a thin presentation layer over the same core engine.

5. **Configuration subsystem**
   - `config_loader.py` and `config.json` form the configuration layer.
   - `config_loader.py` likely reads, validates, and serializes settings so users can persist batch-processing presets.
   - `config.json` is the repository’s default or example configuration, supporting both CLI-driven and GUI-driven runs.

6. **Data flow: input to output**
   - The main flow is: user supplies a directory or set of image paths → interface layer validates options → core processor iterates images → each image is transformed → results are written to the output directory.
   - The README shows the tool supports exact resizing, aspect-ratio-preserving resizing, percentage scaling, and format conversion across common image formats.

7. **Batch processing and filesystem behavior**
   - The app is batch-oriented rather than single-image oriented.
   - It works on directory trees, with optional recursive processing, and uses filesystem paths as the main integration boundary.
   - `pathlib` is likely used for cross-platform path handling, which matters for Windows/macOS/Linux compatibility.

8. **Error handling and resilience**
   - Error handling is a first-class concern in the architecture.
   - The processor must tolerate corrupted files, missing directories, invalid resolution strings, and permission problems without failing the entire batch.
   - This suggests a “process file-by-file, continue on error” execution model with per-item logging.

9. **Logging and observability**
   - `image_processor.log` indicates file-based logging is part of the runtime behavior.
   - Combined with the README’s mention of console/file logs, the system likely records both high-level progress and per-image failures.
   - Logging is an important operational boundary for troubleshooting batch jobs.

10. **Reporting output**
   - The README describes JSON/CSV report generation, so the architecture likely includes a result-summary step after processing.
   - That report layer consumes per-file outcome data from the processor and emits machine-readable artifacts for later analysis or auditing.

11. **External dependencies**
   - The project is Python-based and almost certainly relies on an imaging library such as Pillow for decoding, resizing, and re-encoding images.
   - No external service dependency is indicated; all processing appears local and offline.

12. **Deployment/runtime model**
   - The repo is run directly with Python rather than packaged as a server.
   - There are two execution modes: `python main.py ...` for CLI automation and `python gui_app.py` for interactive use.
   - This makes the architectural boundary primarily between UI/control logic and the shared processing engine, not between client and backend services.

13. **What to draw in an architecture diagram**
   - Show two entry points: CLI and GUI.
   - Both feed into shared modules: config loading and image processing.
   - From image processing, show outputs to the filesystem, logs, and optional reports.
   - Keep the config file and log file as supporting artifacts rather than active components.

Main entry points: [`image_processor.py`](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py) (Processor), [`config_loader.py`](https://github.com/mr-devakumar/bulk-image-handler/blob/main/config_loader.py) (Config loader), [`main.py`](https://github.com/mr-devakumar/bulk-image-handler/blob/main/main.py) (CLI), [`gui_app.py`](https://github.com/mr-devakumar/bulk-image-handler/blob/main/gui_app.py) (GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["Entry points"]
  node_node_main["CLI<br/>entry point<br/>[main.py]"]
  node_node_gui["GUI<br/>entry point<br/>[gui_app.py]"]
end

subgraph group_grp_core["Processing core"]
  node_node_processor["Processor<br/>batch engine<br/>[image_processor.py]"]
  node_node_input_scan["Scan inputs<br/>file discovery<br/>[image_processor.py]"]
  node_node_transform["Transform images<br/>image ops<br/>[image_processor.py]"]
  node_node_error_handling["Error handling<br/>resilience<br/>[image_processor.py]"]
  node_node_results["Results<br/>outcome tracking<br/>[image_processor.py]"]
end

subgraph group_grp_support["Support files"]
  node_node_config_loader["Config loader<br/>config service<br/>[config_loader.py]"]
  node_node_config_json["Default config<br/>config data<br/>[config.json]"]
  node_node_reports["Reports<br/>output generation<br/>[README.md]"]
  node_node_logs["Log file<br/>runtime log"]
  node_node_filesystem[("Filesystem<br/>io boundary")]
  node_node_pillow{{"Imaging lib<br/>dependency<br/>[requirements.txt]"}}
end

node_node_main -->|"load settings"| node_node_config_loader
node_node_gui -->|"load settings"| node_node_config_loader
node_node_config_loader -->|"read/write"| node_node_config_json
node_node_main -->|"invoke"| node_node_processor
node_node_gui -->|"invoke"| node_node_processor
node_node_processor -->|"discover"| node_node_input_scan
node_node_input_scan -->|"read"| node_node_filesystem
node_node_processor -->|"process"| node_node_transform
node_node_transform -->|"use"| node_node_pillow
node_node_transform -->|"write"| node_node_filesystem
node_node_processor -->|"handle failures"| node_node_error_handling
node_node_error_handling -->|"record"| node_node_logs
node_node_processor -->|"collect"| node_node_results
node_node_results -->|"summarize"| node_node_reports
node_node_processor -->|"log"| node_node_logs

click node_node_main "https://github.com/mr-devakumar/bulk-image-handler/blob/main/main.py"
click node_node_gui "https://github.com/mr-devakumar/bulk-image-handler/blob/main/gui_app.py"
click node_node_config_loader "https://github.com/mr-devakumar/bulk-image-handler/blob/main/config_loader.py"
click node_node_config_json "https://github.com/mr-devakumar/bulk-image-handler/blob/main/config.json"
click node_node_processor "https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py"
click node_node_input_scan "https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py"
click node_node_transform "https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py"
click node_node_error_handling "https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py"
click node_node_results "https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py"
click node_node_reports "https://github.com/mr-devakumar/bulk-image-handler/blob/main/README.md"
click node_node_logs "https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.log"
click node_node_pillow "https://github.com/mr-devakumar/bulk-image-handler/blob/main/requirements.txt"

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_node_main,node_node_gui toneBlue
class node_node_processor,node_node_input_scan,node_node_transform,node_node_error_handling,node_node_results toneAmber
class node_node_config_loader,node_node_config_json,node_node_reports,node_node_logs,node_node_filesystem,node_node_pillow toneMint
```

## Components

### Entry points

User-facing automation and interactive interfaces.

- [CLI](https://github.com/mr-devakumar/bulk-image-handler/blob/main/main.py): entry point · Command-line interface for scripted batch runs. · `main.py`
- [GUI](https://github.com/mr-devakumar/bulk-image-handler/blob/main/gui_app.py): entry point · Interactive desktop front end for non-technical use. · `gui_app.py`

### Processing core

Shared batch image workflow and orchestration.

- [Processor](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py): batch engine · Shared batch image processing workflow. · `image_processor.py`
- [Scan inputs](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py): file discovery · Finds source images and walks directories. · `image_processor.py`
- [Transform images](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py): image ops · Performs resize and format conversion work. · `image_processor.py`
- [Error handling](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py): resilience · Continues batch execution while recording per-file failures. · `image_processor.py`
- [Results](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.py): outcome tracking · Collects per-image status for reporting and logs. · `image_processor.py`

### Support files

Persisted configuration, logging, and runtime artifacts.

- [Config loader](https://github.com/mr-devakumar/bulk-image-handler/blob/main/config_loader.py): config service · Reads, validates, and serializes run settings. · `config_loader.py`
- [Default config](https://github.com/mr-devakumar/bulk-image-handler/blob/main/config.json): config data · Persisted configuration preset used by the app. · `config.json`
- [Reports](https://github.com/mr-devakumar/bulk-image-handler/blob/main/README.md): output generation · Produces JSON or CSV summaries after processing. · `README.md`
- [Log file](https://github.com/mr-devakumar/bulk-image-handler/blob/main/image_processor.log): runtime log · File-based operational log for progress and failures. · `image_processor.log`
- **Filesystem**: io boundary · Source and destination directories for batch jobs.
- [Imaging lib](https://github.com/mr-devakumar/bulk-image-handler/blob/main/requirements.txt): dependency · External image decoding and encoding library. · `requirements.txt`

## Connections

- CLI → Config loader: load settings · CLI reads configuration for a run.
- GUI → Config loader: load settings · GUI reads and persists user-selected settings.
- Config loader → Default config: read/write · Configuration is loaded from and saved to disk.
- CLI → Processor: invoke · CLI passes validated options into the shared engine.
- GUI → Processor: invoke · GUI triggers the same batch processor.
- Processor → Scan inputs: discover · Processor locates input images and iterates batches.
- Scan inputs → Filesystem: read · Source paths are read from the filesystem.
- Processor → Transform images: process · Core engine transforms each image.
- Transform images → Imaging lib: use · Imaging operations rely on the external library.
- Transform images → Filesystem: write · Processed images are written to output locations.
- Processor → Error handling: handle failures · Individual file errors do not stop the batch.
- Error handling → Log file: record · Errors and progress are written to logs.
- Processor → Results: collect · Per-file outcomes are accumulated during execution.
- Results → Reports: summarize · Results are emitted as machine-readable reports.
- Processor → Log file: log · Processor emits operational logging.
