# qaptivator/plainimg2 architecture

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

- Interactive diagram: https://gitdiagram.com/qaptivator/plainimg2
- Repository: https://github.com/qaptivator/plainimg2

## Overview

##### Project type and purpose
- This is a Windows-only, native desktop image-viewer application written in C.
- It uses SDL3 and SDL3_image (statically linked) to provide a minimal UI and fast image rendering.
- Build scripts produce both the standalone executable and an Inno Setup installer.

##### File structure
- Top-level files & scripts:
- build.sh / release.sh / tag_release.sh – orchestrate compilation, packaging, versioning
- installer.iss – Inno Setup script to generate a Windows installer
- src/ tree:
- src/main.c – application entry point, SDL event loop, settings & menu logic
- src/SDL3/ & src/SDL3_Image/ – embedded third-party static libraries with include/ lib/ cmake/ pkgconfig subtrees
- VERSION.txt, LICENSE.txt, README.md – metadata & documentation

##### Extract insights from the README
- Single-process, event-driven architecture
- Uses SDL3 for window creation, input handling, rendering surface
- Uses SDL3_image for image file decoding (PNG, JPEG, BMP)
- Settings serialized to settings.txt (simple 0/1 flags)
- Installer registers file associations for common image types

##### Main components
a. Runtime components:
1) plainIMG.exe (C code)
- Core modules:
– Init & teardown (SDL_Init / SDL_Quit)
– Event loop (keyboard, mouse, window events)
– Menu & settings manager (serialize/deserialize settings.txt)
– Image loader (calls IMG_Load via SDL3_image)
– Renderer (SDL_Texture → SDL_RenderCopy)
2) Embedded libraries (static .a):
– libSDL3.a
– libSDL3_image.a
3) Windows OS services:
– Window Manager (create native window, message pump)
– Filesystem (open image, read/write settings)
– Registry (file association via installer)
b. Build-time components:
1) GCC toolchain & windres – compile .c and .rc to .exe
2) CMake files inside src/SDL3 and src/SDL3_Image – document how static libs were built
3) build.sh – invokes windres and gcc to produce debug/release binaries
4) release.sh + installer.iss – wrap binaries into Inno Setup installer
c. External services (optional):
– GitHub (release artifacts upload via release.sh)
– VirusTotal (bad-actor check links in README)

##### Relationships & data flows
- Build pipeline: source files + embedded libs → compile/link (build.sh) → plainIMG.exe
- Packaging pipeline: executable + VERSION.txt + installer script → installer.exe (release.sh)
- Runtime flow:
1) User launches plainIMG.exe (or double-clicks image associated)
2) OS passes image path argument to exe
3) Application loads settings.txt → SDL_Init → IMG_Init
4) IMG_Load reads image bytes → SDL_Texture creation
5) Event loop listens for SDL_Event (keyboard, right-click, drag)
6) Renderer draws texture each frame (with/without antialiasing, black/white bg)
7) User actions toggle flags → settings updated in memory → rendered next frame
8) On exit, serialize settings.txt → SDL_Quit

##### Architectural patterns & design principles
- Layered architecture:
- Presentation layer (SDL window + rendering)
- Application logic layer (event handling, menu, settings)
- Data access layer (SDL_image file I/O, settings.txt I/O)
- Single responsibility per module: loading, rendering, settings management
- Event-driven loop as the core control flow
- Static linking to minimize external deployment dependencies

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build-Time Components
    subgraph "Build-Time Pipeline" 
        direction TB
        BScripts["Build & Release Scripts"]:::scripts
        CC[("GCC & windres\nCompiler Toolchain")]:::tool
        CMakeSDL3["CMake SDL3 Integration"]:::tool
        CMakeIMG["CMake SDL3_image Integration"]:::tool
        BScripts -->|invokes| CC
        CMakeSDL3 -->|defines build| CC
        CMakeIMG -->|defines build| CC
        CC -->|produces| Exe["plainIMG.exe"]:::runtime
        BScripts -->|wraps into| Installer["installer.exe"]:::installer
    end

    %% Installer Definition
    InstallerScript["installer.iss"]:::installer
    BScripts -->|uses| InstallerScript
    Installer -->|registers file assoc.| Registry["Windows Registry"]:::os

    %% Source & Libraries
    subgraph "Source & Embedded Libraries"
        direction TB
        MainC["Application Entry & Core Logic"]:::code
        RC["Windows Resource Definitions"]:::code
        WelcomeBMP["Renderer Assets\n(welcome_black.bmp, welcome_white.bmp)"]:::assets
        SDL3Lib["libSDL3.a"]:::lib
        SDL3Hdr["SDL3 Headers"]:::lib
        IMGLib["libSDL3_image.a"]:::lib
        IMGHdr["SDL3_image Headers"]:::lib

        MainC -->|includes| RC
        MainC -->|loads assets| WelcomeBMP
        Exe -->|links against| SDL3Lib
        Exe -->|links against| IMGLib
        SDL3Hdr -->|compile time| SDL3Lib
        IMGHdr -->|compile time| IMGLib
    end

    %% Runtime Flow
    subgraph "Runtime Flow"
        direction TB
        User["User"]:::external
        OSWin["Windows OS"]:::os
        ExeRuntime["plainIMG.exe"]:::runtime
        SettingsFile["settings.txt"]:::data
        IMGLoad["SDL3_image IMG_Load"]:::runtime
        Texture["SDL_Texture"]:::runtime
        EventLoop["Event Loop"]:::runtime
        Renderer["Renderer\n(SDL_RenderCopy)"]:::runtime

        User -->|launch/double-click| OSWin
        OSWin -->|executes| ExeRuntime
        ExeRuntime -->|reads| SettingsFile
        ExeRuntime -->|calls| IMGLoad
        IMGLoad -->|creates| Texture
        Texture -->|drawn by| Renderer
        ExeRuntime -->|runs| EventLoop
        EventLoop -->|updates| Renderer
        EventLoop -->|toggles flags| SettingsFile
        ExeRuntime -->|writes| SettingsFile
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHub["GitHub Releases"]:::external
        VirusTotal["VirusTotal"]:::external
        BScripts -->|uploads| GitHub
        README["README.md"]:::doc
        README -->|links to| VirusTotal
    end

    %% Documentation & Metadata
    subgraph "Documentation & Metadata"
        direction TB
        README
        Version["VERSION.txt"]:::doc
        License["LICENSE.txt"]:::doc
        GitIgnore[".gitignore"]:::doc
    end

    %% Examples & Resources
    subgraph "Examples & Resources"
        direction TB
        ExampleSettings["examples/default_settings.txt"]:::data
        Icons["icons/"]:::assets
    end

    %% Class Definitions
    classDef scripts fill:#ffeb3b,stroke:#c6892f;
    classDef tool fill:#90caf9,stroke:#1e88e5;
    classDef code fill:#c8e6c9,stroke:#388e3c;
    classDef lib fill:#ffe082,stroke:#ff8f00;
    classDef assets fill:#f8bbd0,stroke:#c2185b;
    classDef runtime fill:#b3e5fc,stroke:#0288d1;
    classDef os fill:#d7ccc8,stroke:#5d4037;
    classDef installer fill:#d1c4e9,stroke:#512da8;
    classDef external fill:#ffcdd2,stroke:#b71c1c;
    classDef data fill:#f0f4c3,stroke:#827717;
    classDef doc fill:#e1bee7,stroke:#6a1b9a;

    %% Click Events
    click MainC "https://github.com/qaptivator/plainimg2/blob/main/src/main.c"
    click RC "https://github.com/qaptivator/plainimg2/blob/main/src/plainIMG.rc"
    click RC "https://github.com/qaptivator/plainimg2/blob/main/src/plainIMG_rc.h"
    click RC "https://github.com/qaptivator/plainimg2/blob/main/src/plainIMG_rc.res"
    click MainC "https://github.com/qaptivator/plainimg2/blob/main/src/plainSTR.h"
    click WelcomeBMP "https://github.com/qaptivator/plainimg2/blob/main/src/welcome_black.bmp"
    click WelcomeBMP "https://github.com/qaptivator/plainimg2/blob/main/src/welcome_white.bmp"
    click SDL3Lib "https://github.com/qaptivator/plainimg2/blob/main/src/SDL3/lib/libSDL3.a"
    click SDL3Hdr "https://github.com/qaptivator/plainimg2/tree/main/src/SDL3/include/SDL3"
    click CMakeSDL3 "https://github.com/qaptivator/plainimg2/tree/main/src/SDL3/lib/cmake/SDL3"
    click IMGLib "https://github.com/qaptivator/plainimg2/blob/main/src/SDL3_Image/lib/libSDL3_image.a"
    click IMGHdr "https://github.com/qaptivator/plainimg2/tree/main/src/SDL3_Image/include/SDL3_image"
    click CMakeIMG "https://github.com/qaptivator/plainimg2/tree/main/src/SDL3_Image/lib/cmake/SDL3_image"
    click BScripts "https://github.com/qaptivator/plainimg2/blob/main/build.sh"
    click BScripts "https://github.com/qaptivator/plainimg2/blob/main/release.sh"
    click BScripts "https://github.com/qaptivator/plainimg2/blob/main/tag_release.sh"
    click BScripts "https://github.com/qaptivator/plainimg2/blob/main/sync.sh"
    click InstallerScript "https://github.com/qaptivator/plainimg2/blob/main/installer.iss"
    click ExampleSettings "https://github.com/qaptivator/plainimg2/blob/main/examples/default_settings.txt"
    click Icons "https://github.com/qaptivator/plainimg2/tree/main/icons/"
    click README "https://github.com/qaptivator/plainimg2/blob/main/README.md"
    click Version "https://github.com/qaptivator/plainimg2/blob/main/VERSION.txt"
    click License "https://github.com/qaptivator/plainimg2/blob/main/LICENSE.txt"
    click GitIgnore "https://github.com/qaptivator/plainimg2/blob/main/.gitignore"
```
