# ryotaushio/obsidian-pdf-plus architecture

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

- Interactive diagram: https://gitdiagram.com/ryotaushio/obsidian-pdf-plus
- Repository: https://github.com/ryotaushio/obsidian-pdf-plus

## Overview

##### Project Type and Purpose
- This is a client-side plugin built to work within the Obsidian application. Its main goal is to supply an enhanced PDF experience by:
– Converting textual backlinks into clickable highlight annotations.
– Extending Obsidian’s PDF viewer without replacing it.
- The README highlights multiple PDF annotation features (both non-invasive [backlink highlighting] and direct PDF editing using pdf-lib) plus comprehensive UI integrations (modals, toolbars, Vim-like keybindings, etc.).

##### Analysis of the File Structure
- Top-Level Files:
– Files like manifest.json, package.json, esbuild.config.mjs, tsconfig.json indicate that the plugin is built with TypeScript, packaged with npm/PNPM, and is designed to integrate with Obsidian via a manifest file.
- The src/ Directory:
– src/main.ts is the plugin’s entry point.
– The “lib” subdirectory contains core utility modules and feature components (commands, copy-link functionality, composer, and more).
– “patchers” contains modules that modify/patch specific behaviors in Obsidian’s internal PDF viewer (e.g., patchers for backlink handling, menu modifications, PDF embedding, etc.).
– “modals” holds various UI dialogs to control annotation, outline editing, and PDF composer actions.
– “post-process” and “user-script” indicate that after initial processing, extra behaviors or custom user interactions are supported.
– “utils” and “vim” subdirectories include support functions and Vim integration modules respectively.
- Other Directories/Files:
– Configuration files (e.g., .editorconfig, eslint.config.mjs) and GitHub workflows reflect supporting the development and release process.

##### Main Components to Illustrate
a. Core Entry & Initialization
– Block for “Main (src/main.ts)” which bootstraps the plugin, registers settings, event handlers, and commands.
b. Module Layers
i. UI/UX Components:
- “Modals” (e.g., annotation-modals, outline-modals, installer-version-modal) for dialogs.
ii. Core Functional Libraries:
- “Lib Modules” (e.g., commands.ts, component.ts, composer.ts, copy-link.ts) that define re-usable operations and core business logic.
iii. Patcher Layer:
- “Patchers” for integrating with the native Obsidian PDF viewer. This includes aspects such as backlink transformation (backlink-visualizer.ts), clipboard management, and internal PDF link enhancements.
iv. Ancillary Modules:
- “Utils” for supporting data manipulation and event handling.
- “Vim” integration layer, which provides Vim-like keybinding processing (visible from files under src/vim).
c. External Libraries & Dependencies:
– Illustrate the integration points with external libraries such as:
- pdf-lib – used for in-PDF annotations,
- monkey-around – for patching private APIs within Obsidian’s PDF viewer.

##### Relationships and Data Flow
- Two main “communication” paths:
– Between the UI layer (modals, toolbar, context menus) and the Core Business Logic (backlink processing, command execution, and PDF manipulation).
– Between the Patcher modules and Obsidian’s underlying PDF viewer. Emphasize that these patches hook into Obsidian’s private APIs.
- Also, illustrate the relationship of configuration and utility modules feeding into these layers.

##### Architectural Patterns and Design Principles
- Modular design: Each folder under “src” corresponds to a distinct feature/module, promoting separation of concerns.
- Event-driven interaction: The integration with Obsidian’s UI (for example, clicking or hovering actions) is managed through command registration and event listeners.
- Extensibility: The plugin is built to work harmoniously with community plugins (Hover Editor, Better Search Views) and supports customization (e.g., link-copy templating, CSS customization for callouts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Obsidian PDF++ Plugin"]:::mainClass
    B["Main (src/main.ts)"]:::coreClass
    A --> B

    subgraph "UI/UX Components"
        C["Modals (src/modals)"]:::uiClass
        D["Toolbar (src/toolbar.ts)"]:::uiClass
        E["Context Menu (src/context-menu.ts)"]:::uiClass
    end

    subgraph "Core Business Logic"
        F["Lib Modules (src/lib)"]:::coreClass
    end

    subgraph "Patcher Layer"
        G["Patchers (src/patchers)"]:::patcherClass
    end

    subgraph "Utility Modules"
        H["Utils (src/utils)"]:::utilsClass
    end

    subgraph "Vim Integration"
        I["Vim Integration (src/vim)"]:::vimClass
    end

    subgraph "External Dependencies"
        J["pdf-lib (src/lib/highlights/write-file/pdf-lib.ts)"]:::externalClass
        K["Monkey-Around (package.json)"]:::externalClass
        L["Obsidian PDF Viewer (Native)"]:::externalClass
    end

    %% Initialization flows
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H
    B --> I

    %% UI to Core Business Logic interaction
    C -->|"commandFlow"| F
    D -->|"commandFlow"| F
    E -->|"commandFlow"| F

    %% Utility support
    H -->|"support"| F

    %% Vim enhancements
    I -->|"enhancements"| F

    %% Core Business using external library
    F -->|"uses"| J

    %% Patcher integration with Obsidian native PDF viewer
    G -->|"patches"| L
    G -->|"modifies"| F

    %% External dependency enabling patchers
    K -->|"enables"| G

    %% Click Events
    click B "https://github.com/ryotaushio/obsidian-pdf-plus/blob/main/src/main.ts"
    click C "https://github.com/ryotaushio/obsidian-pdf-plus/tree/main/src/modals"
    click D "https://github.com/ryotaushio/obsidian-pdf-plus/blob/main/src/toolbar.ts"
    click E "https://github.com/ryotaushio/obsidian-pdf-plus/blob/main/src/context-menu.ts"
    click F "https://github.com/ryotaushio/obsidian-pdf-plus/tree/main/src/lib"
    click G "https://github.com/ryotaushio/obsidian-pdf-plus/tree/main/src/patchers"
    click H "https://github.com/ryotaushio/obsidian-pdf-plus/tree/main/src/utils"
    click I "https://github.com/ryotaushio/obsidian-pdf-plus/tree/main/src/vim"
    click J "https://github.com/ryotaushio/obsidian-pdf-plus/blob/main/src/lib/highlights/write-file/pdf-lib.ts"
    click K "https://github.com/ryotaushio/obsidian-pdf-plus/blob/main/package.json"

    %% Styles
    classDef mainClass fill:#ffefef,stroke:#cc0000,stroke-width:2px;
    classDef coreClass fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef uiClass fill:#e0f7fa,stroke:#00796b,stroke-width:2px;
    classDef patcherClass fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef utilsClass fill:#fffde7,stroke:#f57f17,stroke-width:2px;
    classDef vimClass fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef externalClass fill:#eceff1,stroke:#607d8b,stroke-width:2px;
```
