# gboyd068/obsidian-swiftlatex-render architecture

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

- Interactive diagram: https://gitdiagram.com/gboyd068/obsidian-swiftlatex-render
- Repository: https://github.com/gboyd068/obsidian-swiftlatex-render

## Overview

##### Main Components
a. Host Environment
- Obsidian App (plugin host)
- Obsidian Plugin API & Plugin Manager
b. Plugin Frontend
- manifest.json (plugin metadata)
- main.ts → transpiled/bundled to main.js (entry point)
- UI integration (detects `latex` / `latexsvg` codeblocks, injects rendered output into DOM)
- styles.css (styling of rendered blocks)
c. Compilation Engines (Web Workers + WASM)
- PdfTeXEngine (swiftlatexpdftex.worker.js + pdftex.wasm)
- DvipdfmxEngine (swiftlatexdvipdfm.worker.js + dvipdfm.wasm)
- XeTeXEngine (swiftlatexxetex.worker.js + xetex.wasm)
- Poppler pdftocairo worker (pdftocairo.js + poppler.wasm)
d. Caching & Storage
- Package cache (`.obsidian/swiftlatex-render-cache/package-cache`)
- PDF cache (`.obsidian/swiftlatex-render-cache/pdf-cache`)
e. Remote Services
- TeX Live on-demand package server (https://texlive2.swiftlatex.com/)

##### Relationships & Data Flow
1. User writes a `latex` or `latexsvg` codeblock in Obsidian.
2. Plugin’s main.js (in the main thread) scans markdown and hooks into the rendering pipeline.
3. For each codeblock:
- Select appropriate engine (PdfTeX by default or XeTeX/DVIPDFMX if configured).
- Spawn the corresponding Web Worker.
- Send the raw LaTeX source over `postMessage`.
4. In the Web Worker:
a. Mount cached packages from package-cache into the WASM FS (Emscripten virtual FS).
b. If the code refers to a missing package:
– Fetch `.sty` or other files via HTTP from the remote TeX Live server.
– Store newly fetched packages in the package-cache folder (persisted by the plugin).
– Load them into the WASM FS.
c. Invoke the WASM engine to compile `.tex` → `.pdf` or `.dvi` → `.pdf`.
d. Write output PDF into the WASM FS and `postMessage` it back to main thread.
5. Back in the main thread:
- If the block type is `latexsvg`, spawn the pdftocairo Web Worker.
- Send the PDF blob to pdftocairo worker, convert → SVG, return SVG markup.
- Insert the PDF (as an `<iframe>`/scrollable `
`) or inline SVG into the Obsidian note.
- Update pdf-cache so repeated renders reuse the compiled PDF.

##### Architectural Patterns & Design Principles
- Worker-based isolation: each engine runs in its own thread (non-blocking).
- Virtual FS + caching layer: packages are fetched once, persisted, and reused.
- Plugin modularity: clear separation between the plugin frontend, compilation logic, and remote package service.
- On-demand loading: heavy WASM engines and packages are loaded only when needed.

##### Technologies & Frameworks
- TypeScript for plugin logic (main.ts & engine wrappers)
- Rollup / esbuild for bundling (rollup.config.mjs, esbuild.config.mjs)
- Emscripten-generated WASM modules for TeX engines and Poppler
- Obsidian Plugin API (manifest.json, main.ts hooks)
- HTTP fetch for remote package retrieval
- Local FS via Node/Browser API for caches (`.obsidian/...`)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Host Environment
    subgraph "Obsidian Host" 
        HostApp["Obsidian App"]:::external
        PluginAPI["Obsidian Plugin API & Manager"]:::external
    end

    %% Plugin Frontend
    subgraph "Plugin Frontend" 
        Manifest["manifest.json"]:::config
        RollupCfg["rollup.config.mjs"]:::config
        EsbuildCfg["esbuild.config.mjs"]:::config
        TSConfig["tsconfig.json"]:::config
        MainTS["main.ts"]:::frontend
        Styles["styles.css"]:::frontend
        Examples["examples/"]:::frontend
    end

    %% Compilation Engines & Workers
    subgraph "Engines (Web Workers + WASM)"
        subgraph "PdfTeXEngine" 
            PdfWrapper["PdfTeXEngine.js"]:::engines
            PdfWorker["swiftlatexpdftex.worker.js"]:::engines
        end
        subgraph "DvipdfmxEngine"
            DviWrapper["DvipdfmxEngine.js"]:::engines
            DviWorker["swiftlatexdvipdfm.worker.js"]:::engines
        end
        subgraph "XeTeXEngine"
            XeWrapper["XeTeXEngine.js"]:::engines
            XeWorker["swiftlatexxetex.worker.js"]:::engines
        end
        subgraph "Poppler pdftocairo"
            CairoWorker["pdftocairo.js"]:::engines
        end
    end

    %% Caching & Storage
    subgraph "Caches & Storage"
        PackageCache[".obsidian/.../package-cache"]:::cache
        PDFCache[".obsidian/.../pdf-cache"]:::cache
    end

    %% Remote Service
    TeXLive["TeX Live on-demand<br/>https://texlive2.swiftlatex.com/"]:::external

    %% Documentation & Packaging
    subgraph "Project Files"
        PackageJSON["package.json"]:::config
        PackageLock["package-lock.json"]:::config
        NPMRC[".npmrc"]:::config
        VersionBump["version-bump.mjs"]:::config
        VersionsJSON["versions.json"]:::config
        ESLintRC[".eslintrc"]:::config
        ESLintIgnore[".eslintignore"]:::config
        EditorConfig[".editorconfig"]:::config
        README["README.md"]:::docs
        Changelog["CHANGELOG.md"]:::docs
        License["LICENSE"]:::docs
    end

    %% Data Flow
    User["User writes codeblock"]:::frontend
    User -->|"detect `latex` / `latexsvg`"| MainTS
    MainTS -->|"spawn worker + send LaTeX source"| PdfWorker
    MainTS -->|"spawn worker + send LaTeX source"| DviWorker
    MainTS -->|"spawn worker + send LaTeX source"| XeWorker

    PdfWorker -->|"mount FS from cache"| PackageCache
    DviWorker -->|"mount FS from cache"| PackageCache
    XeWorker -->|"mount FS from cache"| PackageCache

    PdfWorker -->|"fetch missing packages"| TeXLive
    DviWorker -->|"fetch missing packages"| TeXLive
    XeWorker -->|"fetch missing packages"| TeXLive

    PdfWorker -->|"postMessage PDF"| MainTS
    DviWorker -->|"postMessage PDF"| MainTS
    XeWorker -->|"postMessage PDF"| MainTS

    MainTS -->|"store PDF"| PDFCache

    MainTS -->|"if `latexsvg`, spawn pdftocairo"| CairoWorker
    CairoWorker -->|"convert PDF→SVG"| MainTS

    MainTS -->|"inject into DOM"| HostApp

    %% Click Events
    click Manifest "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/manifest.json"
    click RollupCfg "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/rollup.config.mjs"
    click EsbuildCfg "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/esbuild.config.mjs"
    click TSConfig "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/tsconfig.json"
    click MainTS "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/main.ts"
    click Styles "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/styles.css"
    click Examples "https://github.com/gboyd068/obsidian-swiftlatex-render/tree/main/examples/"
    click PdfWrapper "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/PdfTeXEngine.js"
    click PdfWorker "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/swiftlatexpdftex.worker.js"
    click DviWrapper "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/DvipdfmxEngine.js"
    click DviWorker "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/swiftlatexdvipdfm.worker.js"
    click XeWrapper "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/XeTeXEngine.js"
    click XeWorker "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/swiftlatexxetex.worker.js"
    click CairoWorker "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/pdftocairo.js"
    click PackageJSON "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/package.json"
    click PackageLock "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/package-lock.json"
    click NPMRC "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/.npmrc"
    click VersionBump "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/version-bump.mjs"
    click VersionsJSON "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/versions.json"
    click ESLintRC "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/.eslintrc"
    click ESLintIgnore "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/.eslintignore"
    click EditorConfig "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/.editorconfig"
    click README "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/README.md"
    click Changelog "https://github.com/gboyd068/obsidian-swiftlatex-render/blob/main/CHANGELOG.md"
    click License "https://github.com/gboyd068/obsidian-swiftlatex-render/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef engines fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#fc9,stroke:#333,stroke-width:1px
    classDef cache fill:#ddd,stroke:#333,stroke-width:1px
    classDef config fill:#cff,stroke:#333,stroke-width:1px
    classDef docs fill:#eef,stroke:#333,stroke-width:1px
```
