# mlosun/obsidian-sticker-package architecture

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

- Interactive diagram: https://gitdiagram.com/mlosun/obsidian-sticker-package
- Repository: https://github.com/mlosun/obsidian-sticker-package

## Overview

##### Project type and purpose
- This is an Obsidian plugin (“obsidian-sticker-package”) that lets users pick images from a configured vault directory and insert them into the editor as “stickers.”
- It’s built in TypeScript, bundled with esbuild, and packaged/published via GitHub Actions.

##### File structure
- Top level:
- main.ts      – plugin entry point
- manifest.json – defines plugin id, version, permissions, entry file
- styles.css   – optional styling for UI elements
- esbuild.config.mjs, tsconfig.json – build configuration
- version-bump.mjs, versions.json – versioning script/data
- .github/workflows/release.yml – CI/CD pipeline for packaging & releasing
- images/      – screenshots for the README (not shipped in plugin)
- Settings management
- File-system scanning of the Vault’s configured directory
- UI components (context-menu extension, picker modal)
- Command handlers to insert markdown

##### Key insights from the README
- Plugin runtime depends on Obsidian’s Plugin API to register commands, add context-menu items, and render modals.
- Users configure a directory path and default image size via a settings panel.
- At use time, the plugin scans the Vault’s folder, builds a list of image paths, and shows them in a UI picker.

##### Main components
A. Development & Release Pipeline
1. GitHub Repository
2. CI/CD (GitHub Actions → esbuild build → version-bump → GitHub Release)
3. Published .obsidian-plugin zip asset

B. Runtime Environment
1. Obsidian Host (Electron app)
2. Plugin Loader (reads manifest.json → loads bundle)
3. Plugin Core Modules
- Settings Module (persist via Obsidian’s API)
- File Scanner Module (reads Vault folder via Node fs)
- UI Module (context menu extension, modal picker)
- Command Handler (inserts markdown into the editor)
4. Vault File System (user’s .md files + sticker images directory)
5. Editor Canvas (where markdown is inserted)

C. External Services
- GitHub (source repo & releases)
- BRAT or manual install (user-facing install path)

##### Relationships and data flows
- Developer pushes code → CI builds → publishes plugin → user installs plugin
- At runtime:
1. Obsidian reads manifest.json → instantiates plugin bundle
2. Plugin registers commands & context-menu hook
3. User right-clicks in editor → Obsidian calls plugin UI Module
4. UI Module invokes File Scanner → returns image list
5. User selects an image → Command Handler formats markdown and inserts into Editor
6. Settings changes → Settings Module persists via Obsidian API

##### Architectural patterns & principles
- Plugin-based architecture: clear boundary between host (Obsidian) and plugin.
- Modular separation: Settings ↔ File I/O ↔ UI ↔ Editor Command.
- Single-bundle deployment via esbuild for performance & simplicity.
- CI/CD ensures reproducible releases (version bump + GitHub Actions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & Release Pipeline
    subgraph "Development & Release Pipeline"
        direction TB
        Repo["GitHub Repo"]:::external
        CiCd["CI/CD Pipeline"]:::dev
        BuildConfig["Build Configuration"]:::dev
        Versioning["Versioning Scripts & Data"]:::dev
        PackageJson["package.json"]:::dev
        Readme["README.md"]:::dev
        Images["images/"]:::external
        Release["GitHub Release"]:::external
        Asset["Published .obsidian-plugin"]:::external
    end

    Repo -->|"push code"| CiCd
    CiCd -->|"runs esbuild & tsc"| BuildConfig
    BuildConfig -->|"exec version-bump"| Versioning
    Versioning -->|"create release"| Release
    Release -->|"publish asset"| Asset
    Repo --> Readme
    Repo --> PackageJson
    Repo --> Images

    Asset -->|"install"| ObsidianHost

    %% Runtime Environment
    subgraph "Runtime Environment"
        direction TB
        ObsidianHost["Obsidian Host (Electron)"]:::runtime
        PluginLoader["Plugin Loader"]:::runtime
        subgraph "Plugin Core Modules"
            direction TB
            Settings["Settings Module"]:::runtime
            Scanner["File Scanner Module"]:::runtime
            UI["UI Module (Modal & Context Menu)"]:::runtime
            CommandHandler["Command Handler"]:::runtime
        end
        Vault["Vault File System"]:::external
        Editor["Editor Canvas"]:::runtime
    end

    ObsidianHost -->|"read manifest.json"| PluginLoader
    PluginLoader -->|"load bundle (main.ts & styles.css)"| Settings
    PluginLoader --> Settings
    Settings -->|"persistSettings() via API"| ObsidianHost
    UI -->|"scanFolder()"| Scanner
    Scanner -->|"fs.readdir() → imagePaths"| Vault
    UI -->|"display picker"| UI
    UI -->|"user selects image"| CommandHandler
    CommandHandler -->|"insertMarkdown()"| Editor

    %% External Installer Path
    Asset -->|"manual/BRAT install"| ObsidianHost

    %% Click Events
    click CiCd "https://github.com/mlosun/obsidian-sticker-package/blob/master/.github/workflows/release.yml"
    click BuildConfig "https://github.com/mlosun/obsidian-sticker-package/blob/master/.esbuild.config.mjs"
    click BuildConfig "https://github.com/mlosun/obsidian-sticker-package/blob/master/tsconfig.json"
    click Versioning "https://github.com/mlosun/obsidian-sticker-package/blob/master/version-bump.mjs"
    click Versioning "https://github.com/mlosun/obsidian-sticker-package/blob/master/versions.json"
    click PluginLoader "https://github.com/mlosun/obsidian-sticker-package/blob/master/manifest.json"
    click Settings "https://github.com/mlosun/obsidian-sticker-package/blob/master/main.ts"
    click UI "https://github.com/mlosun/obsidian-sticker-package/blob/master/styles.css"
    click Images "https://github.com/mlosun/obsidian-sticker-package/tree/master/images/"
    click PackageJson "https://github.com/mlosun/obsidian-sticker-package/blob/master/package.json"
    click Readme "https://github.com/mlosun/obsidian-sticker-package/blob/master/README.md"

    %% Styles
    classDef dev fill:#cce5ff,stroke:#3399ff
    classDef runtime fill:#ccffcc,stroke:#33cc33
    classDef external fill:#f2f2f2,stroke:#999999
```
