# prasharkaran1009/emagine architecture

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

- Interactive diagram: https://gitdiagram.com/prasharkaran1009/emagine
- Repository: https://github.com/prasharkaran1009/emagine

## Overview

1. **High-level shape**
   - Emagine is a two-tier local application: a **React/Vite frontend** and a **Python backend** exposed through **FastAPI/Uvicorn**.
   - The backend is not just a single service; it contains three functional domains: **image enhancement**, **steganography encoding**, and **steganography decoding**.

2. **Frontend boundary**
   - The `frontend/` folder is a classic single-page app built with **React** and **Vite**.
   - Its pages are split by workflow: `Encode`, `Decode`, and `Enhancement`, which map directly to the backend’s three capabilities.
   - Shared UI lives in reusable components such as upload controls, loaders, pipeline step displays, history panels, and animated state indicators.
   - `ThemeContext` suggests the UI supports theme switching, but it does not appear to affect backend architecture.

3. **Frontend data flow**
   - The frontend is the user interaction layer: users upload images, trigger processing, and view progress/results.
   - It likely sends requests to the backend API for each workflow rather than processing images in the browser.
   - The UI is organized to present step-by-step processing feedback, which matches the backend’s modular pipeline design.

4. **Backend entry point**
   - `backend/app.py` is the top-level API entry point, and the README confirms it is started with `uvicorn app:app`.
   - This makes the backend the orchestration layer that receives requests from the frontend and dispatches them to the appropriate processing subsystem.
   - There is no evidence of a database or message queue; processing appears to be synchronous/local-file based.

5. **Enhancement subsystem**
   - `backend/enhancement/` is the most structured part of the backend and is organized as a pipeline.
   - `main.py` and `pipeline.py` appear to coordinate a multi-step enhancement workflow built from individual modules.
   - The modules implement discrete image-processing stages: **color conversion**, **resizing**, **histogram equalization**, **smoothing**, and **sharpening**.

6. **Enhancement processing model**
   - The README’s workflow matches the code layout: input image → grayscale/conversion → resize/upscale → histogram enhancement → smoothing → sharpening → output.
   - Utility code in `utils/` suggests the enhancement pipeline also includes configuration, image I/O, and some form of analysis or measurement.
   - The `output/` and `input/` directories indicate the enhancement path writes intermediate or final artifacts to the local filesystem.

7. **Super-resolution integration**
   - The enhancement subsystem also includes a bundled **Real-ESRGAN NCNN Vulkan** executable and model files under `tools/realesrgan/`.
   - That means the pipeline is not limited to simple OpenCV filters; it can delegate part of the enhancement work to an external native upscaler.
   - This is an important architectural boundary: Python orchestrates the pipeline, while an external binary performs heavy inference/upscaling.

8. **Encoding/decoding subsystem**
   - `backend/encoding/` and `backend/decoding/` form a second independent capability centered on **steganography**.
   - The encoding side includes C++ source (`steganography.cpp`), a `Makefile`, and a Windows executable (`steg.exe`), plus a Python bridge.
   - The decoding side similarly has a Python bridge, implying the Python backend invokes native steganography tooling rather than implementing the algorithm entirely in Python.

9. **Native bridge boundary**
   - `encode_bridge.py` and `decode_bridge.py` are the integration points between the FastAPI app and the native steganography implementation.
   - This creates a clear separation: API/UI logic stays in Python and React, while compute- or algorithm-specific steganography work happens in compiled code.
   - The presence of a prebuilt `.exe` suggests the repo is optimized for local desktop-style execution rather than cloud deployment.

10. **Filesystem-centered workflow**
   - The backend uses `backend/input/` and `backend/output/` as working directories, which indicates file-based processing rather than purely in-memory transformations.
   - That pattern is common when a service needs to pass images between Python orchestration code and external executables.
   - It also means the main architectural boundary is between request handling and local artifact generation.

11. **Testing and validation**
   - `backend/test_steg.py` and `backend/test_fail.py` suggest there is at least some targeted validation around the steganography path.
   - The test surface is narrower than the application surface, which reinforces that the key complexity lives in the processing pipeline and native bridges.

12. **Technology summary for the diagram**
   - Frontend: **React**, **Vite**, component-based SPA.
   - Backend: **Python**, **FastAPI/Uvicorn**.
   - Image processing: **OpenCV/NumPy**-style modular enhancement pipeline.
   - External compute: **Real-ESRGAN NCNN Vulkan** binary and a **C++ steganography executable**.
   - Storage model: **local file-based input/output staging**, not a database-driven architecture.

13. **Most important diagram boundaries**
   - Draw one boundary between **browser UI** and **FastAPI backend**.
   - Inside the backend, split into three subsystems: **Enhancement**, **Encoding**, and **Decoding**.
   - Inside Enhancement, show a pipeline of modular stages plus an external super-resolution tool.
   - Inside Encoding/Decoding, show Python bridge code calling a native steganography executable.

Main entry points: [`backend/enhancement/pipeline.py`](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/pipeline.py) (Pipeline), [`frontend/src/App.jsx`](https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/App.jsx) (App shell), [`backend/app.py`](https://github.com/prasharkaran1009/emagine/blob/main/backend/app.py) (API app), [`backend/encoding/encode_bridge.py`](https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/encode_bridge.py) (Encode bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["App shell<br/>React SPA<br/>[App.jsx]"]
  node_fe_pages["Workflows<br/>Pages"]
  node_fe_components["Shared UI<br/>Components"]
  node_fe_theme(("Theme<br/>Context<br/>[ThemeContext.jsx]"))
  node_fe_entry["Bootstrap<br/>Vite entry<br/>[main.jsx]"]
end

subgraph group_backend["Backend"]
  node_api_app["API app<br/>[app.py]"]
  node_enc_bridge["Encode bridge<br/>Python bridge<br/>[encode_bridge.py]"]
  node_dec_bridge["Decode bridge<br/>Python bridge<br/>[decode_bridge.py]"]
  node_backend_io[("Work dirs<br/>Filesystem staging")]
end

subgraph group_enhancement["Enhancement"]
  node_enh_main["Enhance main<br/>Pipeline entry<br/>[main.py]"]
  node_enh_pipe["Pipeline<br/>Orchestrator<br/>[pipeline.py]"]
  node_enh_convert["Conversion<br/>Stage<br/>[conversion.py]"]
  node_enh_resize["Resize<br/>Stage<br/>[resize.py]"]
  node_enh_hist["Histogram<br/>Stage<br/>[histogram.py]"]
  node_enh_smooth["Smoothing<br/>Stage<br/>[smoothing.py]"]
  node_enh_sharp["Sharpening<br/>Stage<br/>[sharpening.py]"]
  node_enh_utils["IO & config<br/>Utilities"]
end

subgraph group_native["Native tools"]
  node_realesrgan["Real-ESRGAN<br/>Native upscaler"]
  node_steg_cpp["Steganography<br/>C++ core<br/>[steganography.cpp]"]
  node_steg_exe["steg.exe<br/>Binary<br/>[steg.exe]"]
end

node_fe_entry -->|"boots"| node_fe_app
node_fe_app -->|"routes"| node_fe_pages
node_fe_app -->|"composes"| node_fe_components
node_fe_app -.->|"uses"| node_fe_theme
node_fe_pages -->|"calls"| node_api_app
node_api_app -->|"dispatches"| node_enc_bridge
node_api_app -->|"dispatches"| node_dec_bridge
node_api_app -->|"dispatches"| node_enh_main
node_enh_main -->|"orchestrates"| node_enh_pipe
node_enh_pipe -->|"stage"| node_enh_convert
node_enh_pipe -->|"stage"| node_enh_resize
node_enh_pipe -->|"stage"| node_enh_hist
node_enh_pipe -->|"stage"| node_enh_smooth
node_enh_pipe -->|"stage"| node_enh_sharp
node_enh_pipe -->|"delegates"| node_realesrgan
node_enh_pipe -.->|"uses"| node_enh_utils
node_enc_bridge -->|"invokes"| node_steg_exe
node_enc_bridge -->|"reads/writes"| node_backend_io
node_dec_bridge -->|"invokes"| node_steg_exe
node_dec_bridge -->|"reads/writes"| node_backend_io
node_steg_cpp -.->|"builds"| node_steg_exe

click node_fe_app "https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/App.jsx"
click node_fe_pages "https://github.com/prasharkaran1009/emagine/tree/main/frontend/src/pages"
click node_fe_components "https://github.com/prasharkaran1009/emagine/tree/main/frontend/src/components"
click node_fe_theme "https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/theme/ThemeContext.jsx"
click node_fe_entry "https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/main.jsx"
click node_api_app "https://github.com/prasharkaran1009/emagine/blob/main/backend/app.py"
click node_enc_bridge "https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/encode_bridge.py"
click node_dec_bridge "https://github.com/prasharkaran1009/emagine/blob/main/backend/decoding/decode_bridge.py"
click node_enh_main "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/main.py"
click node_enh_pipe "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/pipeline.py"
click node_enh_convert "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/conversion.py"
click node_enh_resize "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/resize.py"
click node_enh_hist "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/histogram.py"
click node_enh_smooth "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/smoothing.py"
click node_enh_sharp "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/sharpening.py"
click node_enh_utils "https://github.com/prasharkaran1009/emagine/tree/main/backend/enhancement/utils"
click node_realesrgan "https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/tools/realesrgan/realesrgan-ncnn-vulkan.exe"
click node_steg_cpp "https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/steganography.cpp"
click node_steg_exe "https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/steg.exe"
click node_backend_io "https://github.com/prasharkaran1009/emagine/tree/main/backend/input"

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_fe_app,node_fe_pages,node_fe_components,node_fe_theme,node_fe_entry toneBlue
class node_api_app,node_enc_bridge,node_dec_bridge,node_backend_io toneAmber
class node_enh_main,node_enh_pipe,node_enh_convert,node_enh_resize,node_enh_hist,node_enh_smooth,node_enh_sharp,node_enh_utils toneMint
class node_realesrgan,node_steg_cpp,node_steg_exe toneRose
```

## Components

### Frontend

React/Vite single-page app

- [App shell](https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/App.jsx): React SPA · Top-level routed frontend shell · `frontend/src/App.jsx`
- [Workflows](https://github.com/prasharkaran1009/emagine/tree/main/frontend/src/pages): Pages · Encode, Decode, and Enhancement screens · `frontend/src/pages`
- [Shared UI](https://github.com/prasharkaran1009/emagine/tree/main/frontend/src/components): Components · Reusable upload, loading, history, and step components · `frontend/src/components`
- [Theme](https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/theme/ThemeContext.jsx): Context · Theme switching state for the UI · `frontend/src/theme/ThemeContext.jsx`
- [Bootstrap](https://github.com/prasharkaran1009/emagine/blob/main/frontend/src/main.jsx): Vite entry · Frontend entry and startup wiring · `frontend/src/main.jsx`

### Backend

FastAPI orchestration and processing

- [API app](https://github.com/prasharkaran1009/emagine/blob/main/backend/app.py): FastAPI app · Backend entry point exposed through Uvicorn · `backend/app.py`
- [Encode bridge](https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/encode_bridge.py): Python bridge · API-facing bridge into native steganography encoding · `backend/encoding/encode_bridge.py`
- [Decode bridge](https://github.com/prasharkaran1009/emagine/blob/main/backend/decoding/decode_bridge.py): Python bridge · API-facing bridge into native steganography decoding · `backend/decoding/decode_bridge.py`
- [Work dirs](https://github.com/prasharkaran1009/emagine/tree/main/backend/input): Filesystem staging · Local input/output directories used for processing artifacts · `backend/input`

### Enhancement

Image enhancement pipeline and tooling

- [Enhance main](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/main.py): Pipeline entry · Orchestrates the enhancement workflow · `backend/enhancement/main.py`
- [Pipeline](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/pipeline.py): Orchestrator · Coordinates enhancement stages and tool handoff · `backend/enhancement/pipeline.py`
- [Conversion](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/conversion.py): Stage · Color conversion and grayscale preparation · `backend/enhancement/modules/conversion.py`
- [Resize](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/resize.py): Stage · Resizing and upscaling preparation · `backend/enhancement/modules/resize.py`
- [Histogram](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/histogram.py): Stage · Histogram equalization and contrast enhancement · `backend/enhancement/modules/histogram.py`
- [Smoothing](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/smoothing.py): Stage · Noise reduction and smoothing · `backend/enhancement/modules/smoothing.py`
- [Sharpening](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/modules/sharpening.py): Stage · Final detail sharpening · `backend/enhancement/modules/sharpening.py`
- [IO & config](https://github.com/prasharkaran1009/emagine/tree/main/backend/enhancement/utils): Utilities · File I/O, config, and analysis helpers · `backend/enhancement/utils`

### Native tools

Compiled steganography and upscaling binaries

- [Real-ESRGAN](https://github.com/prasharkaran1009/emagine/blob/main/backend/enhancement/tools/realesrgan/realesrgan-ncnn-vulkan.exe): Native upscaler · Bundled NCNN Vulkan super-resolution executable and models · `backend/enhancement/tools/realesrgan/realesrgan-ncnn-vulkan.exe`
- [Steganography](https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/steganography.cpp): C++ core · Native steganography implementation and build target · `backend/encoding/steganography.cpp`
- [steg.exe](https://github.com/prasharkaran1009/emagine/blob/main/backend/encoding/steg.exe): Binary · Prebuilt steganography executable invoked by Python bridge · `backend/encoding/steg.exe`

## Connections

- Bootstrap → App shell: boots · Vite entry loads the React application
- App shell → Workflows: routes · App shell presents the workflow pages
- App shell → Shared UI: composes · Pages rely on shared UI widgets
- App shell → Theme: uses · Theme context provides UI state
- Workflows → API app: calls · Encode, decode, and enhancement workflows invoke backend APIs
- API app → Encode bridge: dispatches · API routes steganography encode requests
- API app → Decode bridge: dispatches · API routes steganography decode requests
- API app → Enhance main: dispatches · API routes enhancement requests
- Enhance main → Pipeline: orchestrates · Main entry hands off to the enhancement pipeline
- Pipeline → Conversion: stage · Preprocesses image channels and format
- Pipeline → Resize: stage · Performs resize/upscale preparation
- Pipeline → Histogram: stage · Applies contrast and histogram enhancement
- Pipeline → Smoothing: stage · Reduces noise and smooths output
- Pipeline → Sharpening: stage · Sharpens final image details
- Pipeline → Real-ESRGAN: delegates · Pipeline can hand off heavy upscaling to native binary
- Pipeline → IO & config: uses · Pipeline depends on file I/O and config helpers
- Encode bridge → steg.exe: invokes · Python bridge calls the compiled encoder
- Encode bridge → Work dirs: reads/writes · Encoding uses local staging files
- Decode bridge → steg.exe: invokes · Python bridge calls the compiled decoder path
- Decode bridge → Work dirs: reads/writes · Decoding uses local staging files
- Steganography → steg.exe: builds · C++ source produces the native executable
