# aidenlx/obsidian-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/aidenlx/obsidian-bridge
- Repository: https://github.com/aidenlx/obsidian-bridge

## Overview

##### Project type and purpose
- This is a TypeScript-based MarginNote 3 “addon” (plugin) whose sole purpose is to bridge content between MarginNote and Obsidian.
- It runs inside MarginNote, listens for user actions or document changes, transforms and packages those into Obsidian-compatible notes, and then hands them off to Obsidian (via the companion app or URI schemes).

##### File structure
- Top-level config files:
- rollup.config.js – bundler entry points and output settings
- tsconfig.json / tsconfig-lib.json – compiler targets and declarations
- Source root (`src/`):
- entry points: index.ts, main.ts, toggle-addon.ts, event-handlers.ts
- “modules” folder: parser.ts, recorder.ts, scan.ts, sender.ts, translate.ts, type-tools.ts, tools.ts, url-obj.ts
- const.ts and return.ts hold constants and return-data schemas
- Package manifest (package.json) indicates dependencies, build & publish scripts, and the addon manifest (mnaddon.json).

##### README for additional insights
- No detailed architecture section, but the purpose is clearly a uni-directional or bi-directional data flow bridge.
- Requires MarginNote v3.7.12+ and relies on its API.

##### Main components
a. Plugin runtime (inside MarginNote)
– Entry module (`main.ts` / `index.ts`)
– Event dispatcher (`event-handlers.ts`)
– Parser: reads MarginNote document structure, annotations
– Recorder: tracks user interactions or edit sessions
– Scanner: extracts metadata, attachments, links
– Translator: maps MN data structures to Obsidian Markdown/JSON
– Sender: invokes Obsidian Companion (HTTP/URI) or writes to local vault
– Tools & Type-Tools: shared utilities, type definitions, URL assembly
c. External systems:
– MarginNote API (host process exposing scriptable events & data)
– Obsidian Vault (local folder file system or remote via companion)
– Optional: MarginNote Companion service (if using HTTP plugin host)

##### Relationships and interactions
- Parser/Scanner feed data into Translator, which emits standard note payloads
- Sender takes payloads and pushes to Obsidian (call-out: “HTTP POST to Companion” or “write markdown file”)

##### Architectural patterns & design principles
- Modular separation: each core function in its own module directory
- Single Responsibility: parser only reads data, translator only transforms, sender only communicates
- Bundling via Rollup to produce one minified JS file (`mnaddon.json` points to it)
- Config-driven: constants and return schemas externalized in `const.ts` and `return.ts`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    MNAPI["MarginNote API\n(v3.7.12+)"]:::external
    ObsidianVault["Obsidian Vault\n(LocalFS/Companion)"]:::external

    %% Add-on Container
    subgraph "MarginNote Add-on Process"
        direction TB
        Index["Entry Points\n(main.ts / index.ts / toggle-addon.ts)"]:::internal
        Event["Event Dispatcher\n(event-handlers.ts)"]:::internal
        Parser["Parser Module\n(parser.ts)"]:::internal
        Recorder["Recorder Module\n(recorder.ts)"]:::internal
        Scanner["Scanner Module\n(scan.ts)"]:::internal
        Translator["Translator Module\n(translate.ts)"]:::internal
        Sender["Sender Module\n(sender.ts)"]:::internal
        Tools["Shared Utilities\n(tools.ts)"]:::internal
        TypeTools["Type Definitions\n(type-tools.ts)"]:::internal
        URLObj["URL Assembly\n(url-obj.ts)"]:::internal
        Const["Constants\n(const.ts)"]:::internal
        Return["Return Schemas\n(return.ts)"]:::internal

        Index -->|"initialize()/toggle()"| Event
        Event -->|"onParseEvent"| Parser
        Event -->|"onRecordEvent"| Recorder
        Event -->|"onScanEvent"| Scanner
        Parser -->|"parsedData"| Translator
        Scanner -->|"scannedData"| Translator
        Recorder -->|"recordData"| Translator
        Translator -->|"notePayload"| Sender
        Sender -->|"POST /sync or write .md"| ObsidianVault

        %% Utilities usage
        Parser --- Tools
        Scanner --- Tools
        Translator --- Tools
        Sender --- Tools
        Translator --- TypeTools
        Sender --- URLObj
        Translator --- Return
        Parser --- Const
    end

    %% Connections to External
    MNAPI -->|"userActions()/docChanges()"| Index
    Sender -->|"webhook/listen(optional)"| MNAPI

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        Rollup["Rollup Config\n(rollup.config.js)"]:::build
        Package["package.json"]:::build
        Manifest["mnaddon.json"]:::build
        TSModules["TS Source\n(src/**/*.ts)"]:::build
        TSModules --> Rollup
        Rollup --> Manifest
        Package --> Manifest
    end

    %% Legend
    subgraph Legend
        direction TB
        A["Internal Modules"]:::internal
        B["External Systems"]:::external
        C["Build & Deployment"]:::build
    end

    classDef internal fill:#D0E6FF,stroke:#005BFF,color:#000;
    classDef external fill:#DFFFD0,stroke:#00A000,color:#000;
    classDef build fill:#FFF2C2,stroke:#FFB400,color:#000;

    %% Click Events
    click Index "https://github.com/aidenlx/obsidian-bridge/blob/master/src/main.ts"
    click Index "https://github.com/aidenlx/obsidian-bridge/blob/master/src/index.ts"
    click Index "https://github.com/aidenlx/obsidian-bridge/blob/master/src/toggle-addon.ts"
    click Event "https://github.com/aidenlx/obsidian-bridge/blob/master/src/event-handlers.ts"
    click Parser "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/parser.ts"
    click Recorder "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/recorder.ts"
    click Scanner "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/scan.ts"
    click Translator "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/translate.ts"
    click Sender "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/sender.ts"
    click Tools "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/tools.ts"
    click TypeTools "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/type-tools.ts"
    click URLObj "https://github.com/aidenlx/obsidian-bridge/blob/master/src/modules/url-obj.ts"
    click Const "https://github.com/aidenlx/obsidian-bridge/blob/master/src/const.ts"
    click Return "https://github.com/aidenlx/obsidian-bridge/blob/master/src/return.ts"
    click Rollup "https://github.com/aidenlx/obsidian-bridge/blob/master/rollup.config.js"
    click Manifest "https://github.com/aidenlx/obsidian-bridge/blob/master/mnaddon.json"
    click Package "https://github.com/aidenlx/obsidian-bridge/blob/master/package.json"
```
