# joethei/obsidian-plantuml architecture

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

- Interactive diagram: https://gitdiagram.com/joethei/obsidian-plantuml
- Repository: https://github.com/joethei/obsidian-plantuml

## Overview

##### Project type and purpose
- This is an Obsidian “Community Plugin” that adds PlantUML rendering support to the Obsidian note-taking app.
- It processes fenced code blocks (`plantuml`, `plantuml-svg`, `plantuml-ascii`) and renders them either via an online PlantUML server or a local JAR.

##### File structure
- Top-level config & metadata: `manifest.json`, `package.json`, `.github/workflows`, `esbuild.config.mjs`, `tsconfig.json`.
- Core plugin code in `src/`:
- `main.ts` – plugin activation, registration of code block processor
- `settings.ts` & `const.ts` – user‐configurable settings (server URL, local JAR path, output format)
- `processors/` – several processor implementations (debounced, local, server)
- `functions.ts` & `processors/processor.ts` – shared utilities, base interfaces
- Static styling: `styles.css`
- Version management: `versions.json`

##### README for additional insights
- Describes two rendering modes: remote server vs. local JAR.
- Mentions support for three languages/formats: PNG, SVG, ASCII.
- Notes linking syntax and caveats for local rendering.

a. Main components
- Obsidian Host (Electron app)
- PlantUML Plugin
- Activation & lifecycle (main.ts)
- Settings UI
- Code block processor manager
- Rendering pipeline (chooses server vs. local)
- PumlView renderer
- External PlantUML Renderer
- Remote PlantUML Server (HTTP endpoint)
- Local PlantUML JAR (spawned Java process)
- Vault (filesystem where notes live)
b. Relationships & interactions
1. User writes fenced code in a note → Obsidian triggers plugin hook.
2. Plugin’s processor reads code block → forwards to either serverProcessor or localProcessor.
3. serverProcessor: HTTP POST to PlantUML server → receives PNG/SVG → embed.
4. localProcessor: spawn `java -jar plantuml.jar` with inputs → capture stdout.
5. embed.ts / PumlView.ts injects rendered output back into the note view.
6. Settings UI allows switching endpoints, formats; settings.ts persists to Obsidian.
c. Architectural patterns & principles
- Plugin modularization: separation of concerns between processors, view, embed logic.
- Strategy pattern for rendering: interchangeable server vs. local processors.
- Debouncing for performance: `debouncedProcessors.ts` to avoid excessive calls on rapid changes.
- Use of Obsidian’s Plugin API to hook into lifecycle and renderer.
d. Relevant technologies/frameworks
- TypeScript, Obsidian Plugin API
- esbuild for bundling
- HTTP fetch API (for server requests)
- Node.js child_process (for local JAR)
- CSS for styling injected views

##### Detailed capture of essential elements
- Break the plugin into:
- Entry point (main.ts)
- Renderer manager (processors/*)
- View layer (PumlView.ts)
- Embedding logic (embed.ts)
- Settings & constants
- Optional paths (SVG vs. ASCII vs. PNG, server vs. local).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Obsidian Core"
        direction TB
        Note["User Note Editor"]:::host
        Vault["Vault (File System)"]:::storage
    end

    subgraph "PlantUML Plugin"
        direction TB
        Main["Plugin Entry & Activation\nmain.ts"]:::plugin
        Settings["Settings UI & Persistence\nsettings.ts"]:::plugin
        Const["Constants & Defaults\nconst.ts"]:::plugin
        Functions["Shared Utilities & Helpers\nfunctions.ts"]:::plugin
        ProcManager["Processor Manager"]:::plugin
        Embed["Embedding Logic\nembed.ts"]:::plugin
        View["Custom View Renderer\nPumlView.ts"]:::plugin

        subgraph "Rendering Engine"
            direction TB
            Debounce["Debounced Processing\ndebouncedProcessors.ts"]:::plugin
            BaseProc["Processor Base Interface\nprocessor.ts"]:::plugin
            Server["Remote Server Strategy\nserverProcessor.ts"]:::plugin
            Local["Local JAR Strategy\nlocalProcessors.ts"]:::plugin
        end
    end

    subgraph "External Renderer Services"
        direction TB
        Remote["PlantUML Server"]:::external
        JavaProc["Java Process (plantuml.jar)"]:::external
    end

    subgraph "Project Config & Metadata"
        direction TB
        Manifest["manifest.json"]:::config
        Package["package.json"]:::config
        ESBuild["esbuild.config.mjs"]:::config
        TSConfig["tsconfig.json"]:::config
        Versions["versions.json"]:::config
        CI1[".github/workflows/main.yml"]:::config
        CI2[".github/workflows/publish.yml"]:::config
        Styles["styles.css"]:::config
    end

    Note -->|"fenced code hook"| Main
    Main --> ProcManager
    ProcManager --> Debounce
    Debounce --> BaseProc
    BaseProc --> Server
    BaseProc --> Local
    Server --> Remote
    Local --> JavaProc
    Server -->|diagram data| Embed
    Local -->|diagram data| Embed
    Embed --> View
    View --> Note

    Settings --> Const
    Settings --> ProcManager
    Const --> Server
    Const --> Local
    Functions --> ProcManager
    Functions --> Embed
    Manifest --> Main
    Package --> Main
    ESBuild --> Main
    TSConfig --> Main
    Versions --> Main
    CI1 --> Main
    CI2 --> Main
    Styles --> Embed

    click Main "https://github.com/joethei/obsidian-plantuml/blob/master/src/main.ts"
    click Settings "https://github.com/joethei/obsidian-plantuml/blob/master/src/settings.ts"
    click Const "https://github.com/joethei/obsidian-plantuml/blob/master/src/const.ts"
    click Functions "https://github.com/joethei/obsidian-plantuml/blob/master/src/functions.ts"
    click BaseProc "https://github.com/joethei/obsidian-plantuml/blob/master/src/processors/processor.ts"
    click Debounce "https://github.com/joethei/obsidian-plantuml/blob/master/src/processors/debouncedProcessors.ts"
    click Server "https://github.com/joethei/obsidian-plantuml/blob/master/src/processors/serverProcessor.ts"
    click Local "https://github.com/joethei/obsidian-plantuml/blob/master/src/processors/localProcessors.ts"
    click Embed "https://github.com/joethei/obsidian-plantuml/blob/master/src/embed.ts"
    click View "https://github.com/joethei/obsidian-plantuml/blob/master/src/PumlView.ts"
    click Manifest "https://github.com/joethei/obsidian-plantuml/blob/master/manifest.json"
    click Package "https://github.com/joethei/obsidian-plantuml/blob/master/package.json"
    click ESBuild "https://github.com/joethei/obsidian-plantuml/blob/master/esbuild.config.mjs"
    click TSConfig "https://github.com/joethei/obsidian-plantuml/blob/master/tsconfig.json"
    click Versions "https://github.com/joethei/obsidian-plantuml/blob/master/versions.json"
    click CI1 "https://github.com/joethei/obsidian-plantuml/blob/master/.github/workflows/main.yml"
    click CI2 "https://github.com/joethei/obsidian-plantuml/blob/master/.github/workflows/publish.yml"
    click Styles "https://github.com/joethei/obsidian-plantuml/blob/master/styles.css"

    classDef host fill:#dddddd,stroke:#333333,color:#000000
    classDef plugin fill:#bbdefb,stroke:#333333,color:#000000
    classDef external fill:#c8e6c9,stroke:#333333,color:#000000
    classDef storage fill:#ffe0b2,stroke:#333333,color:#000000
    classDef config fill:#fff9c4,stroke:#333333,color:#000000
```
