# vivasmaq/disploy architecture

> Architecture diagram of the GitHub repository vivasmaq/disploy, 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/vivasmaq/disploy
- Repository: https://github.com/vivasmaq/disploy

## Overview

##### Project Type and Purpose
- This is a command-line static site generator written in Bash, tailored for photoessays.
- It watches a directory tree of images, videos, and text/metadata files, processes them (with ImageMagick, FFmpeg, a sed-based YAML parser, and a bundled Markdown script), applies HTML templates from a chosen theme, and emits a fully static site under a “_site” folder.

##### Key Architectural Components
a. User Environment
- Terminal / Shell (Bash, Cygwin, OS X, Linux)
- External Dependencies:
– ImageMagick (image processing)
– FFmpeg (video encoding/filtering)
b. expose.sh Orchestrator
– Entry point script.
– Walks the working directory tree (recursively).
– Filters out underscored items.
– Sorts folders/files alphabetically (with optional numeric prefixes).
– For each folder and media item:
- Parses per-folder metadata.txt (optional)
- Parses per-item YAML from sidecar .txt files (via sed regex)
c. Processing Modules
– Image Module
- Reads raw images, generates resized derivatives (e.g., 640.jpg, etc.)
- Applies global/static image-options filters via ImageMagick CLI.
– Video Module
- Converts image sequences to video if folder named “imagesequence”.
- Transcodes each video at configured resolutions and codecs.
- Applies video-options and video-filters via FFmpeg.
- Extracts poster images.
– Markdown Module
- Bundled Markdown.pl script for any text rendering (if used).
d. Templating Engine
– Sed-based simple variable substitution in two template files per theme:
- template.html (global page shell, navigation/menu)
- post-template.html (per-item HTML fragment)
– Supplies built-in variables ({{gallerytitle}}, {{navigation}}, etc.) + YAML metadata.
e. Themes (theme1, theme2, custom)
– Contain CSS, JS, img assets, plus the two HTML templates.
– Copied wholesale into output alongside generated HTML.
f. Output Generator
– Builds a mirrored directory tree under “_site” with:
- index.html at each gallery level (using template.html)
- Per-item pages or inline fragments (via post-template.html)
- Resized images and videos in resolution/codec-named files
- Asset directories for CSS/JS/images

##### Relationships & Data Flow
1. User runs `expose.sh` in a source folder.
2. expose.sh → reads folder structure + metadata → feeds file-by-file to processing modules.
3. Processing modules (ImageMagick, FFmpeg, Markdown.pl) transform media/text → output into a staging “_site” tree.
4. Templating engine molds processed assets into HTML, inserting navigation, titles, and per-item content.
5. Theme assets are copied into the output.
6. Final static site is ready for deployment (no further runtime dependencies).

##### Architectural Patterns & Principles
- Pipeline/Orchestration: expose.sh drives a linear series of transforms.
- Convention-over-Configuration: folder names, file naming patterns, and YAML sidecars encode behavior.
- Pluggable Themes: separation of logic (script) from presentation (templates + assets).
- Extensibility Points:
- Adding new theme directories.
- Tuning sed-based YAML parser for extra keys.
- Hooking into ImageMagick/FFmpeg filter flags.

##### Essential Elements
- Processing modules under the expose.sh umbrella
- External dependencies off to one side
- Input source folder vs. output _site folder
- Theme asset copy step

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Environment"
        Shell["Terminal / Shell"]:::io
    end

    Shell -->|"runs expose.sh"| Orchestrator["expose.sh"]:::processing

    subgraph "Processing Modules"
        IM["ImageMagick Module"]:::processing
        VM["FFmpeg Module"]:::processing
        MD["Markdown Parser"]:::processing
    end

    Orchestrator -->|"process images"| IM
    Orchestrator -->|"process videos"| VM
    Orchestrator -->|"render text"| MD

    subgraph "Templating Engine"
        TE["sed Templating Engine"]:::processing
    end

    IM -->|"resized images"| TE
    VM -->|"processed videos & posters"| TE
    MD -->|"HTML fragments"| TE

    TE -->|"apply templates"| Output["_site Output Directory"]:::io

    subgraph Themes
        subgraph Theme1["theme1"]
            T1GT["template.html"]:::theme
            T1PT["post-template.html"]:::theme
            T1CSS["global.css"]:::theme
            T1JS1["global.js"]:::theme
            T1JS2["cookie.js"]:::theme
            T1JS3["json.js"]:::theme
            T1IMG["img/"]:::theme
        end
        subgraph Theme2["theme2"]
            T2GT["template.html"]:::theme
            T2PT["post-template.html"]:::theme
            T2CSS["global.css"]:::theme
            T2JS["global.js"]:::theme
            T2IMG["img/"]:::theme
        end
    end

    Themes --> TE

    subgraph External["External Dependencies"]
        EM["ImageMagick"]:::external
        EF["FFmpeg"]:::external
    end

    IM --> EM
    VM --> EF

    classDef processing fill:#cce5ff,stroke:#009,stroke-width:1px
    classDef io fill:#d4edda,stroke:#2b8a3e,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#e08d00,stroke-width:1px
    classDef theme fill:#e2e3e5,stroke:#6c757d,stroke-width:1px

    click Orchestrator "https://github.com/vivasmaq/disploy/blob/master/expose.sh"
    click MD "https://github.com/vivasmaq/disploy/blob/master/Markdown_1.0.1/Markdown.pl"
    click T1GT "https://github.com/vivasmaq/disploy/blob/master/theme1/template.html"
    click T1PT "https://github.com/vivasmaq/disploy/blob/master/theme1/post-template.html"
    click T1CSS "https://github.com/vivasmaq/disploy/blob/master/theme1/global.css"
    click T1JS1 "https://github.com/vivasmaq/disploy/blob/master/theme1/global.js"
    click T1JS2 "https://github.com/vivasmaq/disploy/blob/master/theme1/cookie.js"
    click T1JS3 "https://github.com/vivasmaq/disploy/blob/master/theme1/json.js"
    click T1IMG "https://github.com/vivasmaq/disploy/tree/master/theme1/img/"
    click T2GT "https://github.com/vivasmaq/disploy/blob/master/theme2/template.html"
    click T2PT "https://github.com/vivasmaq/disploy/blob/master/theme2/post-template.html"
    click T2CSS "https://github.com/vivasmaq/disploy/blob/master/theme2/global.css"
    click T2JS "https://github.com/vivasmaq/disploy/blob/master/theme2/global.js"
    click T2IMG "https://github.com/vivasmaq/disploy/tree/master/theme2/img/"
```
