# spu7nix/obamify architecture

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

- Interactive diagram: https://gitdiagram.com/spu7nix/obamify
- Repository: https://github.com/spu7nix/obamify

## Overview

##### Project type and purpose
- This is “obamify,” a Rust-based image-morphing application that targets two platforms:
a. A native desktop executable (Windows, macOS, Linux) built with Cargo.
b. A web version (PWA) compiled to WebAssembly via Trunk, served as static assets with a service worker.
- Purpose: take a “source” and “target” image, compute an optimal pixel‐assignment transform (optionally with GPU shaders), animate the morph, record to GIF, and offer preset assignments.

##### File structure
- Top-level CI/CD:
- .github/workflows/… (Rust tests, releases, GitHub/Cloudflare Pages)
- Build config:
- Cargo.toml / Cargo.lock (Rust project)
- rust-toolchain (pinned Rust version)
- Trunk.toml (web build)
- flake.nix / flake.lock (Nix development)
- Frontend assets:
- Presets: presets/*/assignments.json (precomputed transforms)
- Source code: src/
- src/main.rs (native entry point)
- src/lib.rs (shared library)
- src/app/… (core modules): calculate/, gui.rs, morph_sim.rs, preset.rs, gif_recorder.rs
- src/shaders/*.wgsl (WebGPU shaders)
- Web worker glue: worker.js (offload heavy compute in browser).

##### Insights from README
- UI controls a GPU/CPU algorithm with adjustable “resolution,” “proximity importance,” and “algorithm.”
- Building instructions split between native (`cargo run --release`) and web (`trunk serve --release`).
- Deployable as GitHub/Cloudflare Pages and downloadable releases (.exe, .app).

##### Main components and interactions
a. User Interface
- Native GUI (wgpu + window crate) via src/main.rs → src/app/gui.rs
- Web UI (index.html + Wasm) loaded by the browser; PWA shell (manifest.json, sw.js)
b. Compute Engine
- calculate module (drawing_process.rs, util.rs)
- Optional multithreading: web worker (worker.js → src/app/calculate/worker) or native threads
- GPU acceleration: WGSL shaders (jfa.wgsl, shade.wgsl, etc.) invoked via wgpu in both targets
c. Preset Loader
- Reads assignments.json files under presets/ for one-click transforms
d. GIF Recorder
- Captures frame buffers to produce animated GIFs via gif_recorder.rs
e. Build & Deployment
- Cargo workflows build native binaries and Wasm bundles
- Trunk bundles assets, HTML, Wasm, worker.js, shaders, service worker for PWA
- CI/CD pipelines publish to GitHub/Cloudflare Pages and GitHub Releases

##### Architectural patterns & design principles
- Modular separation: GUI ↔ Compute ↔ Presets ↔ Recorder
- Single codebase, multi-target: shared lib.rs and app/ modules reused by native and Wasm
- PWA pattern: service worker caches static assets, manifest enables installability
- Worker pattern: heavy compute offloaded asynchronously

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    User(["User"]):::external

    %% Native Application
    subgraph "Native Application" 
        direction TB
        Native["Native App\n(src/main.rs)"]:::frontend
        GUI_N["GUI Module\n(src/app/gui.rs)"]:::frontend
        SharedLib_N["Shared Library\n(src/lib.rs)"]:::compute
        Compute_DP["Drawing Process\n(src/app/calculate/drawing_process.rs)"]:::compute
        Compute_Util["Utilities\n(src/app/calculate/util.rs)"]:::compute
        Morph["Morph Simulation\n(src/app/morph_sim.rs)"]:::compute
        Worker_N["Worker Threads\n(src/app/calculate/worker/mod.rs)"]:::compute
        PresetLoader_N["Preset Loader\n(src/app/preset.rs)"]:::storage
        GIFRec_N["GIF Recorder\n(src/app/gif_recorder.rs)"]:::compute
    end

    %% Web Application
    subgraph "Web Application (PWA)"
        direction TB
        HTML["PWA Shell\n(index.html)"]:::frontend
        Manifest["Manifest\n(assets/manifest.json)"]:::storage
        SW["Service Worker\n(assets/sw.js)"]:::pipeline
        Wasm["Wasm Bundle\n(trunk build)"]:::frontend
        GUI_W["GUI Module\n(src/app/gui.rs)"]:::frontend
        SharedLib_W["Shared Library\n(src/lib.rs)"]:::compute
        Worker_W["Web Worker\n(worker.js)"]:::compute
        Compute_DP2["Drawing Process\n(src/app/calculate/drawing_process.rs)"]:::compute
        Compute_Util2["Utilities\n(src/app/calculate/util.rs)"]:::compute
        Morph_W["Morph Simulation\n(src/app/morph_sim.rs)"]:::compute
        GIFRec_W["GIF Recorder\n(src/app/gif_recorder.rs)"]:::compute
    end

    %% Data & Assets
    subgraph "Assets & Data"
        direction TB
        Presets["Preset Files\n(presets/*/assignments.json)"]:::storage
        Shaders["WGSL Shaders\n(src/shaders/*.wgsl)"]:::storage
        Icons["Platform Icons\n(assets/linux/, assets/macos/)"]:::storage
    end

    %% Build & Deployment Pipeline
    subgraph "CI/CD & Build"
        direction TB
        CargoT["Cargo Config\n(Cargo.toml, Cargo.lock)"]:::pipeline
        RustTool["Rust Toolchain\n(rust-toolchain)"]:::pipeline
        TrunkCfg["Trunk Config\n(Trunk.toml)"]:::pipeline
        Nix["Nix Flake\n(flake.nix, flake.lock)"]:::pipeline
        CI1["GitHub Actions\n(.github/workflows/rust.yml)"]:::pipeline
        CI2["Release Workflow\n(.github/workflows/release.yaml)"]:::pipeline
        CI3["Pages Workflow\n(.github/workflows/gh_pages.yml)"]:::pipeline
        CI4["CF Pages Workflow\n(.github/workflows/cf_pages.yml)"]:::pipeline
        Artifacts["Artifacts\n(Native Bin, Wasm Assets)"]:::pipeline
        GHPages["GitHub Pages"]:::external
        CFPages["Cloudflare Pages"]:::external
        Releases["GitHub Releases"]:::external
    end

    %% Relationships Native
    User -->|"interacts with"| Native
    Native -->|"uses"| GUI_N
    Native -->|"links"| SharedLib_N
    SharedLib_N --> Compute_DP
    SharedLib_N --> Compute_Util
    SharedLib_N --> Morph
    SharedLib_N --> Worker_N
    Native -->|"loads"| PresetLoader_N
    Native -->|"records"| GIFRec_N
    PresetLoader_N --> Presets
    Compute_DP --> Shaders
    Morph --> Shaders

    %% Relationships Web
    User -->|"visits PWA"| HTML
    HTML -->|"loads"| Manifest
    HTML -->|"registers"| SW
    HTML -->|"fetches"| Wasm
    Wasm -->|"invokes"| GUI_W
    Wasm -->|"links"| SharedLib_W
    SharedLib_W --> Compute_DP2
    SharedLib_W --> Compute_Util2
    SharedLib_W --> Morph_W
    HTML -->|"spawns"| Worker_W
    Worker_W --> Compute_DP2
    Worker_W --> Compute_Util2
    GUI_W --> GIFRec_W
    Presets -->|"served via HTTP"| HTML
    Compute_DP2 --> Shaders
    Morph_W --> Shaders

    %% Build pipeline flows
    CargoT -->|"build native"| Artifacts
    RustTool --> Artifacts
    TrunkCfg -->|"build web"| Artifacts
    Nix --> Artifacts
    CI1 --> Artifacts
    CI2 --> Releases
    CI3 --> GHPages
    CI4 --> CFPages

    %% Click Events
    click Native "https://github.com/spu7nix/obamify/blob/main/src/main.rs"
    click SharedLib_N "https://github.com/spu7nix/obamify/blob/main/src/lib.rs"
    click GUI_N "https://github.com/spu7nix/obamify/blob/main/src/app/gui.rs"
    click Compute_DP "https://github.com/spu7nix/obamify/blob/main/src/app/calculate/drawing_process.rs"
    click Compute_Util "https://github.com/spu7nix/obamify/blob/main/src/app/calculate/util.rs"
    click Worker_N "https://github.com/spu7nix/obamify/blob/main/src/app/calculate/worker/mod.rs"
    click Morph "https://github.com/spu7nix/obamify/blob/main/src/app/morph_sim.rs"
    click PresetLoader_N "https://github.com/spu7nix/obamify/blob/main/src/app/preset.rs"
    click GIFRec_N "https://github.com/spu7nix/obamify/blob/main/src/app/gif_recorder.rs"
    click Shaders "https://github.com/spu7nix/obamify/blob/main/src/shaders/*.wgsl"
    click HTML "https://github.com/spu7nix/obamify/blob/main/index.html"
    click Manifest "https://github.com/spu7nix/obamify/blob/main/assets/manifest.json"
    click SW "https://github.com/spu7nix/obamify/blob/main/assets/sw.js"
    click Worker_W "https://github.com/spu7nix/obamify/blob/main/worker.js"
    click TrunkCfg "https://github.com/spu7nix/obamify/blob/main/Trunk.toml"
    click RustTool "https://github.com/spu7nix/obamify/tree/main/rust-toolchain"
    click CargoT "https://github.com/spu7nix/obamify/blob/main/Cargo.toml"
    click Nix "https://github.com/spu7nix/obamify/blob/main/flake.nix"
    click CI1 "https://github.com/spu7nix/obamify/blob/main/.github/workflows/rust.yml"
    click CI2 "https://github.com/spu7nix/obamify/blob/main/.github/workflows/release.yaml"
    click CI3 "https://github.com/spu7nix/obamify/blob/main/.github/workflows/gh_pages.yml"
    click CI4 "https://github.com/spu7nix/obamify/blob/main/.github/workflows/cf_pages.yml"

    %% Styles
    classDef frontend fill:#d0e7ff,stroke:#004c99,color:#000;
    classDef compute fill:#d6f5d6,stroke:#008000,color:#000;
    classDef storage fill:#ffe5b4,stroke:#cc8400,color:#000;
    classDef pipeline fill:#e0e0e0,stroke:#666666,color:#000;
    classDef external fill:none,stroke:#999999,stroke-dasharray: 5 5,color:#999;
```
