# aidenlx/marginnote-companion architecture

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

- Interactive diagram: https://gitdiagram.com/aidenlx/marginnote-companion
- Repository: https://github.com/aidenlx/marginnote-companion

## Overview

##### Project Type and Purpose
- This is an Obsidian plugin (“MarginNote Companion”) whose job is to bridge data between MarginNote 3 and Obsidian. It listens for user actions (paste, commands, gestures) inside Obsidian, fetches the selected note/selection/tree from MarginNote (via the obsidian-bridge add-on), transforms it (images, backlinks, metadata), applies user-configurable templates, and inserts the resulting Markdown into Obsidian.

##### Main Components
a. Host Environment
- Obsidian App (v0.12.17+) with Plugin API
- MarginNote 3 + obsidian-bridge add-on
b. Plugin Package
- manifest.json – plugin metadata & permissions
- main.js (built) – entry point that registers commands, UI, event listeners
- styles.css – default styling
c. Source Modules (src/)
1. Receivers – listen for Obsidian events
- autopaste.ts, input-handler.ts, insert.ts, rec-indicator.less
2. Handlers – coordinate data fetch & processing
- -new-video.ts, frontmatter.ts, mn-data-handler.ts
3. Controls – UI components & context-menu items
- heading-alias.ts/.less, heading-src.ts/.less, util.ts/.less
4. Settings UI
- setting-tab.ts/.less, settings.ts
5. Template Engine
- template.ts, note-template.ts, sel-template.ts, toc-template.ts, basic/…
6. Macros & Utilities
- macro-handler.ts, autodef.ts, misc.ts, cm-tools.ts
7. Language Support
- lang/en.ts, zh.ts, helper.ts
8. “ToSource” Helpers
- src-button.ts, src-cmd.ts, src-menu.ts, to-src.ts
9. Typings & Config
- svg.d.ts, tpl-cfg.d.ts, types.d.ts

##### Relationships & Data Flow
- User triggers an action in Obsidian (context menu, hotkey, paste) →
Receivers capture the event →
Handlers call into mn-data-handler to request JSON/XML from MarginNote via obsidian-bridge →
Data passes through macros & utilities →
Template engine renders Markdown according to user templates →
Frontmatter handler injects metadata (aliases, backlink) →
Controls/UI modules decide where and how to insert →
The plugin uses Obsidian API to insert or replace content in the editor →
Settings UI allows live configuration of commands, templates, and languages.

##### Architectural Patterns & Key Technologies
- Event-driven architecture: Receivers → Handlers → Template → Output
- Modular separation: each concern (UI, data fetch, templating, macros) lives in its own folder
- Plugin build pipeline: esbuild.js + rollup.config.js compile & bundle TS into main.js for Obsidian
- Styling with Less (.less files)
- Jest for unit tests (jest.config.ts)
- Language files for i18n support

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Systems
    Obsidian["Obsidian Host"]:::external
    MarginNote["MarginNote 3 + obsidian-bridge"]:::external

    %% Plugin Core
    subgraph "Plugin Core" 
        subgraph "Receivers" 
            Autopaste["autopaste.ts"]:::module
            InputHandler["input-handler.ts"]:::module
            InsertRecv["insert.ts"]:::module
            RecIndicator["rec-indicator.less"]:::module
        end
        subgraph "Handlers"
            AddVideo["add-new-video.ts"]:::module
            Frontmatter["frontmatter.ts"]:::module
            MNDataHandler["mn-data-handler.ts"]:::module
        end
        subgraph "Template Engine"
            TemplateCore["template.ts"]:::module
            NoteTpl["note-template.ts"]:::module
            SelTpl["sel-template.ts"]:::module
            TocTpl["toc-template.ts"]:::module
            subgraph "Basic Templates"
                CommentTpl["comment.ts"]:::module
                ExcerptTpl["excerpt.ts"]:::module
                LinkTpl["link.ts"]:::module
                QueryTpl["query.ts"]:::module
                TextTpl["text.ts"]:::module
            end
        end
        subgraph "Controls"
            HeadingAlias["heading-alias.ts"]:::module
            HeadingAliasStyle["heading-alias.less"]:::module
            HeadingSrc["heading-src.ts"]:::module
            HeadingSrcStyle["heading-src.less"]:::module
            UtilsCtl["utils.ts"]:::module
            UtilsStyle["util.less"]:::module
        end
        subgraph "Settings UI"
            SettingTab["setting-tab.ts"]:::module
            SettingTabStyle["setting-tab.less"]:::module
            SettingsLogic["settings.ts"]:::module
        end
        subgraph "Macros & Utilities"
            MacroHandler["macro-handler.ts"]:::module
            AutoDef["autodef.ts"]:::module
            MiscUtil["misc.ts"]:::module
            CMTools["cm-tools.ts"]:::module
        end
        subgraph "Language Support"
            LangEn["en.ts"]:::module
            LangZh["zh.ts"]:::module
            LangHelper["helper.ts"]:::module
        end
        subgraph "ToSource Helpers"
            SrcButton["src-button.ts"]:::module
            SrcCmd["src-cmd.ts"]:::module
            SrcMenu["src-menu.ts"]:::module
            ToSrc["to-src.ts"]:::module
        end
        subgraph "Typings & Config"
            SVGTypings["svg.d.ts"]:::module
            TplCfgTypings["tpl-cfg.d.ts"]:::module
            TypesTypings["types.d.ts"]:::module
        end
    end

    %% Build & Packaging
    subgraph "Build Pipeline"
        Esbuild["esbuild.js"]:::build
        Rollup["rollup.config.js"]:::build
        Manifest["manifest.json"]:::artifact
        MainJS["main.js"]:::artifact
    end

    %% Data Flow
    UserAction["User Action"]:::user
    UserAction -->|triggers| Autopaste
    UserAction -->|triggers| InputHandler
    UserAction -->|triggers| InsertRecv

    Autopaste -->|event| AddVideo
    InputHandler -->|event| MNDataHandler
    InsertRecv -->|event| MNDataHandler

    MNDataHandler -->|fetch JSON/XML| MarginNote
    MarginNote -->|response| MNDataHandler

    MNDataHandler -->|data| MacroHandler
    MacroHandler -->|processed| TemplateCore
    TemplateCore -->|renders Markdown| NoteTpl
    TemplateCore --> SelTpl
    TemplateCore --> TocTpl
    TemplateCore --> CommentTpl
    TemplateCore --> ExcerptTpl
    TemplateCore --> LinkTpl
    TemplateCore --> QueryTpl
    TemplateCore --> TextTpl

    TemplateCore -->|metadata| Frontmatter
    Frontmatter -->|annotated| Controls

    Controls -->|insertion| Obsidian

    SettingsLogic -->|configures| Autopaste
    SettingsLogic -->|configures| TemplateCore
    SettingsLogic -->|configures| LangHelper

    LangHelper -->|provides| LangEn
    LangHelper --> LangZh

    SrcButton --> Controls
    SrcCmd --> Controls
    SrcMenu --> Controls
    ToSrc --> Controls

    %% Build connections
    Esbuild -->|bundles TS| Rollup
    Rollup -->|outputs| MainJS
    Manifest -->|metadata| MainJS
    MainJS -->|entry point| PluginCore[Plugin Core]

    %% Click Events
    click Manifest "https://github.com/aidenlx/marginnote-companion/blob/master/manifest.json"
    click Esbuild "https://github.com/aidenlx/marginnote-companion/blob/master/esbuild.js"
    click Rollup "https://github.com/aidenlx/marginnote-companion/blob/master/rollup.config.js"
    click MainJS "https://github.com/aidenlx/marginnote-companion/blob/master/src/mn-main.ts"
    click Autopaste "https://github.com/aidenlx/marginnote-companion/blob/master/src/receivers/autopaste.ts"
    click InputHandler "https://github.com/aidenlx/marginnote-companion/blob/master/src/receivers/input-handler.ts"
    click InsertRecv "https://github.com/aidenlx/marginnote-companion/blob/master/src/receivers/insert.ts"
    click RecIndicator "https://github.com/aidenlx/marginnote-companion/blob/master/src/receivers/rec-indicator.less"
    click AddVideo "https://github.com/aidenlx/marginnote-companion/blob/master/src/handlers/add-new-video.ts"
    click Frontmatter "https://github.com/aidenlx/marginnote-companion/blob/master/src/handlers/frontmatter.ts"
    click MNDataHandler "https://github.com/aidenlx/marginnote-companion/blob/master/src/handlers/mn-data-handler.ts"
    click HeadingAlias "https://github.com/aidenlx/marginnote-companion/blob/master/src/controls/heading-alias.ts"
    click HeadingAliasStyle "https://github.com/aidenlx/marginnote-companion/blob/master/src/controls/heading-alias.less"
    click HeadingSrc "https://github.com/aidenlx/marginnote-companion/blob/master/src/controls/heading-src.ts"
    click HeadingSrcStyle "https://github.com/aidenlx/marginnote-companion/blob/master/src/controls/heading-src.less"
    click UtilsCtl "https://github.com/aidenlx/marginnote-companion/blob/master/src/controls/utils.ts"
    click UtilsStyle "https://github.com/aidenlx/marginnote-companion/blob/master/src/controls/util.less"
    click SettingTab "https://github.com/aidenlx/marginnote-companion/blob/master/src/setting-tab.ts"
    click SettingTabStyle "https://github.com/aidenlx/marginnote-companion/blob/master/src/setting-tab.less"
    click SettingsLogic "https://github.com/aidenlx/marginnote-companion/blob/master/src/settings.ts"
    click TemplateCore "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/template.ts"
    click NoteTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/note-template.ts"
    click SelTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/sel-template.ts"
    click TocTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/toc-template.ts"
    click CommentTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/basic/comment.ts"
    click ExcerptTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/basic/excerpt.ts"
    click LinkTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/basic/link.ts"
    click QueryTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/basic/query.ts"
    click TextTpl "https://github.com/aidenlx/marginnote-companion/blob/master/src/template/basic/text.ts"
    click MacroHandler "https://github.com/aidenlx/marginnote-companion/blob/master/src/macros/macro-handler.ts"
    click AutoDef "https://github.com/aidenlx/marginnote-companion/blob/master/src/macros/autodef.ts"
    click MiscUtil "https://github.com/aidenlx/marginnote-companion/blob/master/src/misc.ts"
    click CMTools "https://github.com/aidenlx/marginnote-companion/blob/master/src/cm-tools.ts"
    click LangEn "https://github.com/aidenlx/marginnote-companion/blob/master/src/lang/en.ts"
    click LangZh "https://github.com/aidenlx/marginnote-companion/blob/master/src/lang/zh.ts"
    click LangHelper "https://github.com/aidenlx/marginnote-companion/blob/master/src/lang/helper.ts"
    click SrcButton "https://github.com/aidenlx/marginnote-companion/blob/master/src/to-source/src-button.ts"
    click SrcCmd "https://github.com/aidenlx/marginnote-companion/blob/master/src/to-source/src-cmd.ts"
    click SrcMenu "https://github.com/aidenlx/marginnote-companion/blob/master/src/to-source/src-menu.ts"
    click ToSrc "https://github.com/aidenlx/marginnote-companion/blob/master/src/to-src.ts"
    click SVGTypings "https://github.com/aidenlx/marginnote-companion/blob/master/src/typings/svg.d.ts"
    click TplCfgTypings "https://github.com/aidenlx/marginnote-companion/blob/master/src/typings/tpl-cfg.d.ts"
    click TypesTypings "https://github.com/aidenlx/marginnote-companion/blob/master/src/typings/types.d.ts"
    click JestConfig "https://github.com/aidenlx/marginnote-companion/blob/master/jest.config.ts"
    click TSConfig "https://github.com/aidenlx/marginnote-companion/blob/master/tsconfig.json"
    click ESLint "https://github.com/aidenlx/marginnote-companion/blob/master/ .eslintrc.js"

    %% Styles
    classDef external fill:#BBE1FA,stroke:#3282B8,color:#0B132B
    classDef module fill:#C0FDFB,stroke:#2E8B57,color:#0B3D91
    classDef build fill:#FFD6A5,stroke:#FF8C00,color:#5F370E
    classDef artifact fill:#FFE5B4,stroke:#FF8C00,color:#5F370E
    classDef user fill:#E0BBE4,stroke:#957DAD,color:#4A235A
```
