# ggml-org/media architecture

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

- Interactive diagram: https://gitdiagram.com/ggml-org/media
- Repository: https://github.com/ggml-org/media

## Overview

##### Project type and purpose
- This is an open-source command-line media‐card generator (“Social media stuff”) that uses llama.cpp to produce annotated PNG cards.
- Key clues: a `cards/` folder full of shell scripts invoking llama.cpp, an `output.png` example in the README, plus asset directories for fonts and logos.

##### File structure
- Top-level:
- README.md – project description and usage
- .gitignore
- cards/ – individual `*.sh` scripts and a `common.sh` helper
- fonts/ – ProFont assets used for text rendering
- logo/ – logo image(s) to overlay on cards
- scripts/ – supporting scripts (e.g. `sync-to-ggml-org.sh`)
- Patterns:
- A simple pipeline: user runs one of the `cards/*.sh` entry points
- Shared logic in `cards/common.sh`
- External binary dependency: llama.cpp
- Asset directories for text rendering and branding
- A post-processing/publish step (sync script)

##### README for additional insights
- Usage example: `./cards/llama.cpp-feature-cache-reuse.sh && open ./cards/output.png`

a. Main components
- CLI Scripts (cards/*.sh) – entry points
- Common Shell Library (cards/common.sh) – shared helper functions
- llama.cpp Engine – local LLM inference binary + model files
- Assets
– Fonts (fonts/ProFontWinTweaked/)
– Logo (logo/)
- Output Generator – image composition logic inside common.sh
- Sync/Deployment Script (scripts/sync-to-ggml-org.sh)
b. Relationships & interactions
- User → chooses and runs a CLI script
- CLI script → sources `common.sh` → invokes llama.cpp with selected model
- llama.cpp → computes text output → piped back to script
- common.sh → uses fonts and logo assets → composes PNG (e.g. via ImageMagick)
- CLI script → writes `cards/output.png`
- (Optional) sync script → pushes generated cards to remote repo or website
c. Architectural patterns & principles
- Pipeline pattern: linear flow from input (shell script) → processing (llama.cpp + rendering) → output
- Modularization: extract shared steps into `common.sh`
- Asset segregation: separate directories for fonts and logos
- CLI-driven extensibility: new card types just add new `*.sh` under `cards/`
d. Key technologies
- Shell scripting (bash)
- llama.cpp LLM inference
- Image manipulation tools (e.g. ImageMagick or similar, invoked by common.sh)
- Git for versioning
- Optional sync via custom shell script

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    User["User"]:::user

    %% Documentation
    doc["README.md"]:::doc
    gitignore1[".gitignore"]:::doc
    gitignore2["cards/.gitignore"]:::doc

    %% CLI Entry Scripts
    subgraph "CLI Entry Scripts"
        script1["llama.cpp-feature-cache-reuse.sh"]:::script
        script2["llama.cpp-feature-speculative-decoding.sh"]:::script
        script3["llama.cpp-model-gemma-3-test.sh"]:::script
        script4["llama.cpp-model-nomic-embed-text-v2.sh"]:::script
        script5["llama.cpp-model-qwen-3.sh"]:::script
    end

    common["common.sh"]:::script

    %% Engine
    subgraph "llama.cpp Engine"
        engine["llama.cpp binary + models"]:::engine
    end

    %% Assets
    subgraph "Assets"
        fonts["Fonts"]:::asset
        logo["Logo"]:::asset
    end

    composer["Image Composer (ImageMagick)"]:::process
    output["Output: output.png"]:::output
    sync["Sync to ggml org"]:::sync

    %% Flow
    User -->|runs| script1
    User -->|runs| script2
    User -->|runs| script3
    User -->|runs| script4
    User -->|runs| script5

    script1 -->|"sources common.sh"| common
    script2 --> common
    script3 --> common
    script4 --> common
    script5 --> common

    common -->|"invokes"| engine
    engine -->|"stdout text"| common

    common -->|"renders image"| composer
    fonts --> composer
    logo --> composer

    composer -->|"writes"| output
    output -->|"triggers"| sync

    %% Documentation links
    User --- doc
    doc --- gitignore1
    doc --- gitignore2

    %% Click Events
    click script1 "https://github.com/ggml-org/media/blob/master/cards/llama.cpp-feature-cache-reuse.sh"
    click script2 "https://github.com/ggml-org/media/blob/master/cards/llama.cpp-feature-speculative-decoding.sh"
    click script3 "https://github.com/ggml-org/media/blob/master/cards/llama.cpp-model-gemma-3-test.sh"
    click script4 "https://github.com/ggml-org/media/blob/master/cards/llama.cpp-model-nomic-embed-text-v2.sh"
    click script5 "https://github.com/ggml-org/media/blob/master/cards/llama.cpp-model-qwen-3.sh"
    click common "https://github.com/ggml-org/media/blob/master/cards/common.sh"
    click fonts "https://github.com/ggml-org/media/tree/master/fonts/ProFontWinTweaked/"
    click logo "https://github.com/ggml-org/media/tree/master/logo/"
    click sync "https://github.com/ggml-org/media/blob/master/scripts/sync-to-ggml-org.sh"
    click doc "https://github.com/ggml-org/media/blob/master/README.md"
    click gitignore1 "https://github.com/ggml-org/media/blob/master/.gitignore"
    click gitignore2 "https://github.com/ggml-org/media/blob/master/cards/.gitignore"

    %% Styles
    classDef user fill:#eef,stroke:#333,stroke-width:1px
    classDef script fill:#ddf,stroke:#333,stroke-width:1px
    classDef engine fill:#cfc,stroke:#333,stroke-width:1px
    classDef asset fill:#fcf,stroke:#333,stroke-width:1px
    classDef process fill:#ff9,stroke:#333,stroke-width:1px
    classDef output fill:#fc9,stroke:#333,stroke-width:1px
    classDef sync fill:#9cf,stroke:#333,stroke-width:1px
    classDef doc fill:#eee,stroke:#333,stroke-width:1px
```
