# phuongtna1/gsu25ai07-deblur-app architecture

> Architecture diagram of the GitHub repository phuongtna1/gsu25ai07-deblur-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phuongtna1/gsu25ai07-deblur-app
- Repository: https://github.com/phuongtna1/gsu25ai07-deblur-app

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Python web application built on Streamlit.
- Purpose: allow users to upload a blurred image, pick one of six deep-learning or diffusion models, tune sampling parameters, and get an interactive deblurred result.

##### Main components
a. Streamlit UI (app.py)
- Handles file upload, cropping/resizing, parameter sliders, model selection, display & download.
b. Preprocessing & Postprocessing (utils.py)
- Image I/O (PIL/OpenCV), cropping, resizing, brightness/hue adjustments, slider comparison widget.
c. Model definitions
- standalone_model.py: CNN, UNet, ResNet architectures
- diff_model.py: Diffusion (DDPM/DDIM) variants of those architectures
d. Inference orchestration (utils.py)
- Loads the selected model, fetches weights, runs forward pass, returns output tensor → PIL image
e. Model weights storage
- a models.zip stored on Google Drive; auto-download & extract on first run, then cached locally
f. External services & dependencies
- Google Drive (for weights)
- PyTorch, Streamlit, image-processing libs defined in requirements.txt

##### Relationships & data flow
1. User uploads image → Streamlit UI
2. UI → Preprocessor (utils)
3. Preprocessor outputs tensor → Inference orchestrator
4. Orchestrator calls Model Loader → downloads/extracts weights if missing
5. Orchestrator instantiates correct model class (from standalone_model or diff_model) → runs inference
6. Raw output tensor → Postprocessor (utils) → PIL image
7. Streamlit UI displays before/after slider, zoom & brightness controls
8. User triggers “Download” → UI streams file to browser

##### Architectural patterns & design principles
- Monolithic MVC-style separation:
- View = Streamlit components in app.py
- Controller = utils.py orchestrating I/O & inference
- Model layer = standalone_model.py + diff_model.py
- Lazy loading / caching of large assets (models.zip)
- Single process, request-driven pipeline (no microservices)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer: UI
    StreamlitUI["Streamlit UI"]:::ui
    StreamlitUI -->|"PIL Image"| Preprocessor

    %% Middle Layer: Compute
    Preprocessor["Preprocessor"]:::compute
    Preprocessor -->|"Tensor"| InferenceOrch
    InferenceOrch["Inference Orchestrator"]:::compute
    InferenceOrch -->|"Instantiate Model"| ModelLayer
    InferenceOrch -->|"Raw Tensor"| Postprocessor
    Postprocessor["Postprocessor"]:::compute
    Postprocessor -->|"PIL Image"| StreamlitUI
    StreamlitUI -->|"Download Trigger"| DownloadHandler["Download Handler"]:::ui

    %% Bottom Layer: Model and Storage
    subgraph "Model Layer"
        direction TB
        StandaloneModels["Standalone Models\n(CNN/UNet/ResNet)"]:::model
        DiffusionModels["Diffusion Models\n(DDPM/DDIM)"]:::model
    end
    ModelLayer --> StandaloneModels
    ModelLayer --> DiffusionModels

    WeightsCache[(Local Model Cache)]:::storage
    GoogleDrive["Google Drive"]:::external
    StandaloneModels -->|"Load Weights"| WeightsCache
    DiffusionModels -->|"Load Weights"| WeightsCache
    WeightsCache -->|"Cache Miss"| GoogleDrive
    GoogleDrive -->|"Download Zip"| WeightsCache

    %% External Dependencies
    ExternalDeps["External Dependencies\n(PyTorch, Streamlit,\nPIL/OpenCV)"]:::external

    %% Data flow arrow from External Deps annotation
    ExternalDeps --- InferenceOrch

    %% Click Events
    click StreamlitUI "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/app.py"
    click Preprocessor "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/utils.py"
    click InferenceOrch "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/utils.py"
    click Postprocessor "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/utils.py"
    click StandaloneModels "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/standalone_model.py"
    click DiffusionModels "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/diff_model.py"
    click ExternalDeps "https://github.com/phuongtna1/gsu25ai07-deblur-app/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef compute fill:#d4edda,stroke:#155724,color:#155724;
    classDef model fill:#fff3cd,stroke:#856404,color:#856404;
    classDef storage fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
