# onlytk/stickerpicker architecture

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

- Interactive diagram: https://gitdiagram.com/onlytk/stickerpicker
- Repository: https://github.com/onlytk/stickerpicker

## Overview

##### Project Type and Purpose
- This is an open‑source Matrix “sticker picker” widget with two halves:
a) A Python‑based CLI/library for creating and converting sticker packs (build‑time).
b) A static, client‑side web widget (runtime) that can be embedded in any Matrix client (e.g., Element).
- The CLI ingests JSON definitions in `packs/`, fetches or converts emote images, and writes out the processed pack metadata and assets. The web folder hosts the widget’s HTML, JS, CSS, and the generated pack metadata for static deployment.

##### Main Components of the System
A. Build‑Time (Developer Machine)
- Sticker CLI (Python package in `sticker/`):
– `stickerimport.py` reads `packs/*.json`, downloads or references image assets.
– `scalar_convert.py` optionally produces Scalar‐compatible pack JSON (`packs/scalar-*.json`).
– Utility modules under `sticker/lib` handle HTTP, Matrix API calls, JSON I/O.
- Output artifacts:
– `emotes/` (images + `index.json`, `pack.json`)
– `web/packs/` (`emotes.json`, `index.json`)
B. Static Hosting (e.g., GitHub Pages)
- Serves:
– Emote images & JSON from `emotes/`
– Web widget under `web/` (HTML, JS bundles, CSS, `web/packs/`)
C. Runtime (End‑User Matrix Client)
- Matrix client (Element Web／iOS／Android) loads the widget via an iframe pointing to `index.html`.
- Widget modules (`web/src/*.js` + `web/lib/htm/preact.js`):
– Reads `web/packs/index.json` to list sticker packs.
– On pack selection, loads that pack’s `emotes.json`.
– On sticker click, uses `widget-api.js` to postMessage a Matrix sticker event back to the host.
- Client widget API interacts over postMessage and the Matrix Widget protocol.
- Frequently‑used stickers are stored in browser localStorage.

##### Relationships and Interactions
- Developer invokes the Sticker CLI → processes `packs/` → emits assets and JSON into `emotes/` and `web/packs/`.
- CI/deployment pushes these static folders plus the `web/` source to a static file server.
- End user’s Matrix client embeds the widget iframe → widget loads static assets (HTML/JS/CSS/JSON/images).
- Widget ↔ Matrix client communicate via the Widget postMessage API:
- Widget sends “sticker selected” events up.
- Client may send down “update frequently‑used” or theming info.

##### Architectural Patterns and Design Principles
- Clear separation of concerns:
- Build‑time toolchain (Python CLI) vs. run‑time widget (JS/CSS/HTML).
- No dynamic back‑end server—entirely static hosting.
- Modular front‑end: small UI components (search, spinner, list).
- Use of standard browser APIs (fetch, postMessage) and a lightweight view library (Preact + htm).
- Configurable pack definitions in JSON—easy to extend or import from other services (e.g., Telegram, Scalar).

##### Key Technologies and Frameworks
- Python 3 (+ requirements in `requirements.txt`), `setup.py` for packaging the CLI.
- `sticker/lib`: custom matrix/HTTP utils.
- Front‑end:
- JavaScript modules under `web/src/`
- Preact + htm (`web/lib/htm/preact.js`)
- ESInstall loader (`web/esinstall.js`)
- CSS/SASS for styling (`web/style/`)
- Static hosting via GitHub Pages or any web server.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer / CLI
    subgraph "Developer / CLI"
        direction TB
        SI["stickerimport.py"]:::buildtime
        SC["scalar_convert.py"]:::buildtime
        PM["pack.py"]:::buildtime
        MV["get_version.py"]:::buildtime
        VR["version.py"]:::buildtime
        SSET["setup.py"]:::buildtime
        REQ["requirements.txt"]:::buildtime
        LIBM["matrix.py"]:::buildtime
        LIBU["util.py"]:::buildtime
        PD["packs/*.json"]:::buildtime
    end

    %% Build Artifacts
    subgraph "Build Artifacts"
        direction TB
        EMJ["emotes/index.json"]:::assets
        EMK["emotes/pack.json"]:::assets
        WPJ1["web/packs/index.json"]:::assets
        WPJ2["web/packs/emotes.json"]:::assets
    end

    %% Static File Server
    subgraph "Static File Server"
        direction TB
        SHE["web/index.html"]:::hosting
        ESL["web/esinstall.js"]:::hosting
        PKG["web/package.json"]:::hosting
        STY1["web/style/index.css"]:::hosting
        STY2["web/style/index.sass"]:::hosting
        SPN1["web/style/spinner.css"]:::hosting
        SPN2["web/style/spinner.sass"]:::hosting
        EMDS["emotes/"]:::assets
        WPDS["web/packs/"]:::assets
    end

    %% End-User Matrix Client
    subgraph "End-User Matrix Client"
        direction TB
        MC["Matrix Client (Element)"]:::runtime
        IFRAME["Widget iFrame"]:::runtime
        subgraph "Widget iFrame"
            direction TB
            MBI["web/src/index.js"]:::runtime
            SB["web/src/search-box.js"]:::runtime
            SPN["web/src/spinner.js"]:::runtime
            FU["web/src/frequently-used.js"]:::runtime
            WAPI["web/src/widget-api.js"]:::runtime
            PHT["web/lib/htm/preact.js"]:::runtime
        end
    end

    %% Data Flows
    PD -->|reads pack defs| SI
    PD -->|reads pack defs| SC
    SI -->|generates emotes JSON/images| EMJ
    SI -->|generates emotes JSON/images| EMK
    SC -->|generates web packs JSON| WPJ1
    SC -->|generates web packs JSON| WPJ2

    EMJ -->|deployed to| EMDS
    EMK -->|deployed to| EMDS
    WPJ1 -->|deployed to| WPDS
    WPJ2 -->|deployed to| WPDS

    EMDS -->|serves assets| MC
    WPDS -->|serves JSON| IFRAME
    SHE -->|serves HTML/JS/CSS| IFRAME
    ESL -->|serves loader| IFRAME
    PKG -->|serves config| IFRAME
    STY1 -->|serves styles| IFRAME
    STY2 -->|serves styles| IFRAME
    SPN1 -->|serves styles| IFRAME
    SPN2 -->|serves styles| IFRAME

    IFRAME -->|fetch index.json| WPJ1
    IFRAME -->|fetch emotes.json| WPJ2
    IFRAME -->|fetch images| EMDS
    WAPI -->|postMessage sticker-selected| MC

    %% Click Events
    click SI "https://github.com/onlytk/stickerpicker/blob/master/sticker/stickerimport.py"
    click SC "https://github.com/onlytk/stickerpicker/blob/master/sticker/scalar_convert.py"
    click PM "https://github.com/onlytk/stickerpicker/blob/master/sticker/pack.py"
    click MV "https://github.com/onlytk/stickerpicker/blob/master/sticker/get_version.py"
    click VR "https://github.com/onlytk/stickerpicker/blob/master/sticker/version.py"
    click SSET "https://github.com/onlytk/stickerpicker/blob/master/setup.py"
    click REQ "https://github.com/onlytk/stickerpicker/blob/master/requirements.txt"
    click LIBM "https://github.com/onlytk/stickerpicker/blob/master/sticker/lib/matrix.py"
    click LIBU "https://github.com/onlytk/stickerpicker/blob/master/sticker/lib/util.py"
    click PD "https://github.com/onlytk/stickerpicker/tree/master/packs/"
    click EMJ "https://github.com/onlytk/stickerpicker/blob/master/emotes/index.json"
    click EMK "https://github.com/onlytk/stickerpicker/blob/master/emotes/pack.json"
    click WPJ1 "https://github.com/onlytk/stickerpicker/blob/master/web/packs/index.json"
    click WPJ2 "https://github.com/onlytk/stickerpicker/blob/master/web/packs/emotes.json"
    click SHE "https://github.com/onlytk/stickerpicker/blob/master/web/index.html"
    click ESL "https://github.com/onlytk/stickerpicker/blob/master/web/esinstall.js"
    click PKG "https://github.com/onlytk/stickerpicker/blob/master/web/package.json"
    click PHT "https://github.com/onlytk/stickerpicker/blob/master/web/lib/htm/preact.js"
    click MBI "https://github.com/onlytk/stickerpicker/blob/master/web/src/index.js"
    click SB "https://github.com/onlytk/stickerpicker/blob/master/web/src/search-box.js"
    click SPN "https://github.com/onlytk/stickerpicker/blob/master/web/src/spinner.js"
    click FU "https://github.com/onlytk/stickerpicker/blob/master/web/src/frequently-used.js"
    click WAPI "https://github.com/onlytk/stickerpicker/blob/master/web/src/widget-api.js"

    %% Styles
    classDef buildtime fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef assets fill:#E6FFED,stroke:#28a745,color:#22863a
    classDef hosting fill:#F0F0F5,stroke:#6f42c1,color:#5a32a3
    classDef runtime fill:#FFF5E5,stroke:#d15704,color:#b31d00
```
