# creeston/ggallery architecture

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

- Interactive diagram: https://gitdiagram.com/creeston/ggallery
- Repository: https://github.com/creeston/ggallery

## Overview

##### Project Type & Purpose
- Type: ggallery is a command-line Python tool designed for generating a static HTML photo gallery website based on a YAML configuration file.
- Purpose: The tool processes a YAML specification to define galleries, photo albums, and associated metadata, then uses plugin-based renderers and storage providers (local file system and Azure Blob Storage) to generate a static website with features such as thumbnail generation and customizable templates.

##### Analyzing the File Structure
- Top-Level Files/Folders:
- Files like .gitignore, LICENSE, README.md, and setup.py indicate a packaged tool.
- The examples folder contains YAML examples and configurations for various use cases (e.g., local and Azure Blob example configurations).
- The docs folder is used for generated static output (site index, etc.).
- Core Code (inside the “ggallery” directory):
- __main__.py: Entry point for the command-line interface.
- config.py: Likely handles configuration settings based on YAML and environment variables.
- gallery_generator.py: Contains the main engine that processes the gallery YAML and coordinates generation.
- model.py: Contains domain models (e.g., albums, photos).
- Plugins and Providers:
- The “renderers” subdirectory includes the base and custom renderer implementations. The ggallery.renderers.BaseRenderer defines how custom rendering plugins should be built.
- The “storage” subdirectory implements different data storage backends (local_storage.py and azure_blob_storage.py) as well as a base provider for extensibility.
- The “image” subdirectory includes functionality for thumbnail generation (thumbnail_creator.py) and related image processing utilities.
- The “utils” subdirectory contains helper functions, likely used across modules.
- Additional elements:
- Static folder contains assets like the SVG image used in the README.
- Configuration files (pyproject.toml, requirements.txt) specify dependencies and build/deployment instructions.

##### Key Components & Their Relationships
a. Entry Point:
- __main__.py for CLI interaction, which parses command-line arguments (e.g., path to gallery.yaml) and invokes the gallery generation process.
b. Core Engine:
- gallery_generator.py: Coordinates overall process—reading the YAML file, selecting appropriate plugins, initiating image processing (thumbnail generation), and orchestrating the final static site generation.
c. Configuration Module:
- config.py: Manages runtime configuration from the YAML file and environment variables.
d. Domain Model:
- model.py: Holds definitions for galleries, albums, photos, which are used through the processing pipeline.
e. Plugin-Based Renderers:
- Under “renderers”: The abstract BaseRenderer class and its concrete implementations allow the project to extend functionality through custom templates (e.g., the nanogallery2 plugin).
f. Storage Providers:
- Under “storage”: Abstractions and implementations for local storage and Azure Blob Storage. These modules handle integration with external data sources and storage backends.
g. Image Processing:
- Under “image”: thumbnail_creator.py and associated utilities in “utils” for processing images and creating thumbnails.
h. External Dependencies:
- Pillow for image processing.
- PyYAML for parsing YAML specifications.
- azure-storage-blob for Azure integration.

- The CLI (__main__.py) initiates the process by reading configuration (via config.py and the YAML file).
- The core gallery generator (gallery_generator.py) uses the domain model (model.py) to construct gallery data.
- It then delegates rendering to a selected Renderer plugin (from ggallery/renderers).
- Simultaneously, it accesses storage providers (local_storage.py or azure_blob_storage.py) to retrieve or store image data.
- The image module (thumbnail_creator.py) is invoked for processing images before file inclusion.
- The output (static HTML, thumbnails, etc.) is written to the designated output directory (as specified in the YAML file, e.g., docs).

##### Architectural Patterns & Design Principles
- Plugin-based architecture: Renderers and storage providers are abstracted via base classes (BaseRenderer, base_provider.py), enabling easy integration of new implementations.
- Separation of Concerns: Distinct modules for configuration, core gallery generation, rendering, image processing, and storage.
- Dependency Injection: The core engine can dynamically select storage and renderer plugins based on the YAML configuration.
- Modularity: File structure indicates logical grouping of functionalities into separate directories, making the system easily extensible and maintainable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Config
    subgraph "CLI & Config"
        CLI("CLI/Entry Point"):::internal
        CONFIG("Configuration Manager"):::internal
    end

    %% Core Engine
    subgraph "Core Engine"
        GEN("Gallery Generator"):::internal
        MODEL("Domain Model"):::internal
    end

    %% Renderers Plugin
    subgraph "Renderers Plugin"
        RENDER_BASE("Base Renderer"):::plugin
        RENDER_IMPORT("Import Renderer"):::plugin
    end

    %% Storage Providers
    subgraph "Storage Providers"
        STORAGE_BASE("Base Storage Provider"):::storage
        STORAGE_LOCAL("Local Storage"):::storage
        STORAGE_AZURE("Azure Blob Storage"):::storage
    end

    %% Image Processing Module
    subgraph "Image Processing Module"
        IMAGE_THUMB("Thumbnail Creator"):::image
        IMAGE_UTILS("Image Utils"):::image
    end

    %% Output Directory
    OUTPUT("Output Directory"):::output

    %% Connections
    CLI -->|"Parses YAML"| CONFIG
    CONFIG -->|"Provides_Config"| GEN
    CLI -->|"Triggers_Generation"| GEN
    GEN -->|"Builds_Model"| MODEL
    GEN -->|"Delegates_Rendering"| RENDER_BASE
    GEN -->|"Delegates_Rendering"| RENDER_IMPORT
    GEN -->|"Uses_Storage"| STORAGE_BASE
    STORAGE_BASE -->|"ImplementedBy"| STORAGE_LOCAL
    STORAGE_BASE -->|"ImplementedBy"| STORAGE_AZURE
    GEN -->|"Processes_Images"| IMAGE_THUMB
    GEN -->|"Processes_Images"| IMAGE_UTILS
    GEN -->|"Writes_Site"| OUTPUT

    %% Click Events
    click CLI "https://github.com/creeston/ggallery/blob/main/ggallery/__main__.py"
    click CONFIG "https://github.com/creeston/ggallery/blob/main/ggallery/config.py"
    click GEN "https://github.com/creeston/ggallery/blob/main/ggallery/gallery_generator.py"
    click MODEL "https://github.com/creeston/ggallery/blob/main/ggallery/model.py"
    click RENDER_BASE "https://github.com/creeston/ggallery/blob/main/ggallery/renderers/base_renderer.py"
    click RENDER_IMPORT "https://github.com/creeston/ggallery/blob/main/ggallery/renderers/import_renderer.py"
    click STORAGE_BASE "https://github.com/creeston/ggallery/blob/main/ggallery/storage/base_provider.py"
    click STORAGE_LOCAL "https://github.com/creeston/ggallery/blob/main/ggallery/storage/local_storage.py"
    click STORAGE_AZURE "https://github.com/creeston/ggallery/blob/main/ggallery/storage/azure_blob_storage.py"
    click IMAGE_THUMB "https://github.com/creeston/ggallery/blob/main/ggallery/image/thumbnail_creator.py"
    click IMAGE_UTILS "https://github.com/creeston/ggallery/blob/main/ggallery/utils/image_utils.py"
    click OUTPUT "https://github.com/creeston/ggallery/tree/main/docs/"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef plugin fill:#B4F7A6,stroke:#000,stroke-width:2px;
    classDef storage fill:#F7E7A6,stroke:#000,stroke-width:2px;
    classDef image fill:#F7A6F7,stroke:#000,stroke-width:2px;
    classDef output fill:#F7F7A6,stroke:#000,stroke-width:2px;
```
