# kemus/obsidian-plugins-annotations architecture

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

- Interactive diagram: https://gitdiagram.com/kemus/obsidian-plugins-annotations
- Repository: https://github.com/kemus/obsidian-plugins-annotations

## Overview

##### Project Type and Purpose
- This is a **full-stack (frontend-only) plugin** for Obsidian, written in TypeScript, bundled via esbuild.
- Purpose: augment Obsidian’s “Community plugins” settings pane with per-plugin annotation fields that users can edit, format in Markdown, and persist.

##### File Structure
- **src/**: All TypeScript source modules
- main.ts – entry point, registers the plugin with Obsidian’s API
- settings_tab.ts – defines the UI injection into the Settings pane
- annotation_control.ts & manageAnnotations.ts – business logic for annotation creation, display, persistence
- grammar.pegjs & peggy.mjs – grammar definition + parser for custom parsing of annotations (e.g., Obsidian links)
- defaults*.ts, utils.ts, types*.ts – configuration, utilities, shared type definitions
- **legacy_settings/** + versions.json – code paths to migrate old annotation formats
- **styles/styles.css** – plugin-specific styling to accompany the injected UI
- **esbuild.config.mjs** – build script, generates dist/main.js and dist/styles.css
- **manifest.json** – Obsidian plugin manifest (name, version, entry points)

##### README for Insights
- The plugin hooks into Obsidian’s “Community plugins” pane
- It uses the Obsidian Plugin API to fetch installed plugins, show textareas, and persist data
- User interactions (typing, locking, toggling) lead to data updates in the plugin’s storage

##### Main Components & Their Relationships
a. Obsidian Host
- Provides Plugin API: register settings pane tab, read/write plugin data, fetch installed plugin metadata
b. Plugin Entry (main.js)
- Bootstraps the plugin, calls app.workspace.registerSettingsTab()
c. SettingsTab UI
- Renders a list of installed plugins + annotation controls
- Uses annotation_control.ts to create/edit UI widgets
d. Annotation Manager
- manageAnnotations.ts handles loading/saving, lock toggles, migrations via defaults_legacy.ts & legacy_settings JSON
e. Storage Layer
- Obsidian’s data store (plugin-specific JSON under .obsidian/plugins/plugins-annotations)
f. Grammar Parser (Peggy)
- grammar.pegjs + peggy.mjs compile-time parser to process Markdown/links in annotations
g. Styles
- styles.css applies plugin-specific CSS in settings pane

Obsidian API → Plugin Entry → SettingsTab UI
SettingsTab UI ↔ Annotation Manager ↔ Storage
Annotation Manager → Legacy Settings (migration)
SettingsTab UI → Grammar Parser (on display/render)

##### Architectural Patterns & Technologies
- **Modular MVC-style** separation:
- View: settings_tab.ts, annotation_control.ts
- Controller: manageAnnotations.ts
- Model: storage JSON, types.ts
- **Build & Bundling**: esbuild (esbuild.config.mjs)
- **Parsing**: Peggy (grammar.pegjs + peggy.mjs)
- **Styling**: plain CSS (styles/styles.css)

##### Essential Elements
- Component names (Main, SettingsTab, AnnotationControl, ManageAnnotations, PeggyParser, Storage)
- Data stores (plugin JSON folder, legacy_settings)
- Obsidian API boundaries
- Build pipeline (esbuild.config → main.js + styles.css)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External System
    Host["Obsidian Host"]:::external

    %% Subgraph: Plugin Core
    subgraph "Plugin Core"
        Main["Plugin Entry (Main)"]:::core
        ManageAnnotations["Annotation Manager"]:::core
        Defaults["Default Configuration"]:::core
        DefaultsLegacy["Legacy Defaults"]:::core
        Types["Type Definitions"]:::model
        Utils["Utility Functions"]:::model
        Manifest["Plugin Manifest"]:::config
        Esbuild["Build & Bundling Config"]:::config
    end

    %% Subgraph: UI Components
    subgraph "UI Components"
        SettingsTab["SettingsTab UI"]:::ui
        AnnotationControl["Annotation Control"]:::ui
        Styles["Plugin Stylesheet"]:::ui
    end

    %% Subgraph: Storage & Legacy Data
    subgraph "Storage & Legacy Data"
        Storage["Plugin Storage (JSON)"]:::storage
        LegacyData["Legacy Settings Data"]:::storage
        Versions["Versions Mapping"]:::storage
    end

    %% Subgraph: Parser
    subgraph "Grammar Parser (Peggy)"
        Grammar["Grammar Definition"]:::parser
        Peggy["Peggy Runtime"]:::parser
    end

    %% Subgraph: Model Definitions
    TypesLegacy["Legacy Type Definitions"]:::model

    %% Connections
    Host -->|"registerSettingsTab()"| Main
    Main -->|"init UI"| SettingsTab
    SettingsTab -->|"render controls"| AnnotationControl
    SettingsTab -->|"user input"| ManageAnnotations
    ManageAnnotations -->|"loadData()/saveData()"| Storage
    ManageAnnotations -->|"migrate()"| DefaultsLegacy
    ManageAnnotations -->|"uses mapping"| Versions
    SettingsTab -->|"parseMarkdown()"| Grammar
    Grammar -->|"compile-time"| Peggy
    SettingsTab -->|"apply styles"| Styles
    Esbuild -->|"bundles"| Main
    Esbuild -->|"bundles"| Styles
    Manifest -->|"loaded by"| Host

    %% Click Events
    click Main "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/main.ts"
    click SettingsTab "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/settings_tab.ts"
    click AnnotationControl "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/annotation_control.ts"
    click ManageAnnotations "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/manageAnnotations.ts"
    click Defaults "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/defaults.ts"
    click DefaultsLegacy "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/defaults_legacy.ts"
    click LegacyData "https://github.com/kemus/obsidian-plugins-annotations/blob/main/legacy_settings/data_1_0.json"
    click Versions "https://github.com/kemus/obsidian-plugins-annotations/blob/main/versions.json"
    click Grammar "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/grammar.pegjs"
    click Peggy "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/peggy.mjs"
    click Types "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/types.ts"
    click Utils "https://github.com/kemus/obsidian-plugins-annotations/blob/main/src/utils.ts"
    click Styles "https://github.com/kemus/obsidian-plugins-annotations/blob/main/styles/styles.css"
    click Esbuild "https://github.com/kemus/obsidian-plugins-annotations/blob/main/esbuild.config.mjs"
    click Manifest "https://github.com/kemus/obsidian-plugins-annotations/blob/main/manifest.json"

    %% Styles
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ui fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef storage fill:#fff3b0,stroke:#333,stroke-width:1px
    classDef parser fill:#ffe5b0,stroke:#333,stroke-width:1px
    classDef model fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef config fill:#f0f0f0,stroke:#333,stroke-width:1px
```
