# kaiiiz/obsidian-raindrop-highlights-plugin architecture

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

- Interactive diagram: https://gitdiagram.com/kaiiiz/obsidian-raindrop-highlights-plugin
- Repository: https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin

## Overview

##### Project Type and Purpose
- This is an Obsidian community plugin (TypeScript + Svelte) that synchronizes article highlights/annotations from Raindrop.io into an Obsidian vault.

##### File Structure
- src/main.ts: plugin entry point (registers commands, settings, event hooks)
- src/api.ts & src/tokenManager.ts: handle Raindrop HTTP API calls, rate-limiting, authentication
- src/sync.ts: orchestrates fetch-transform-write pipeline for “full sync”, “incremental sync” and “single bookmark” operations
- src/renderer.ts: transforms raw API data into front-matter + Markdown via Nunjucks templates (src/templates & src/assets)
- src/modal/*.svelte & *.ts: UI layer for configuring API token and managing collections in Obsidian’s modal dialogs
- src/settings.ts & src/constants.ts: plugin configuration definitions and defaults
- manifest.json & package.json & esbuild.config.mjs: plugin metadata, dependency management, build pipeline

##### Core Components & Interactions
a. Obsidian Host Environment
- Plugin Loader (reads manifest.json, initializes main.ts)
- Vault FS API (read/write Markdown files)
- Settings Storage (persist plugin settings via Obsidian API + localStorage for token)
- Command Palette / UI Integration

b. UI Layer (Svelte Modals)
- API Token Modal
- Collections Management Modal
––– these emit events/commands back to main.ts for persisting settings

c. Business Logic Layer
- Command Handlers (registered in main.ts)
- Sync Service (sync.ts)
- Template Engine (renderer.ts + Nunjucks templates)
- API Service (api.ts + tokenManager.ts, handles OAuth token, rate-limit, pagination)

d. External Service
- Raindrop.io REST API (HTTPS)

e. Local Storage & File System
- localStorage (stores API token)
- Obsidian Vault FS (writes .md files with front-matter and highlights)

##### Architectural Patterns & Design Principles
- Modular layering: clear separation of UI (Svelte) → orchestration (main) → services (Sync, API) → persistence (Vault, localStorage)
- Template-driven rendering: using Nunjucks as pluggable template engine
- Command-based triggers: all sync operations are exposed as Obsidian commands
- Rate-limit resilience: API service waits and retries when HTTP 429 received

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Obsidian Host Container
    subgraph "Obsidian Host Environment"
        direction TB

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            APITokenModal(["API Token Modal"]):::ui
            CollectionsModal(["Collections Management Modal"]):::ui
            BreakingChangeModal(["Breaking Change Notice Modal"]):::ui
        end

        %% Core Services
        subgraph "Core Services"
            direction TB
            Main(["Plugin Entry Point\n(main.ts)"]):::core
            SyncService(["Sync Service\n(sync.ts)"]):::core
            APIService(["API Service\n(api.ts)"]):::core
            TokenManager(["Token Manager\n(tokenManager.ts)"]):::core
            TemplateEngine(["Template Engine\n(renderer.ts)"]):::core
            subgraph "Templates & Assets"
                direction TB
                DefaultTemplate(["defaultTemplate.njk"]):::asset
                DefaultMetadataTemplate(["defaultMetadataTemplate.njk"]):::asset
                TemplatesDir(["templates/*"]):::asset
            end
            Settings(["Settings & Constants\n(settings.ts, constants.ts)"]):::core
            Types(["Types & Declarations\n(types.ts, custom.d.ts)"]):::core
        end

        %% Storage Layer
        subgraph "Storage"
            direction TB
            VaultFS(["Vault FS"]):::storage
            LocalStorage(["localStorage"]):::storage
        end
    end

    %% External Service
    RaindropAPI(["Raindrop.io REST API"]):::external

    %% Data Flows
    APITokenModal -->|"saveToken() / emit event"| Main
    CollectionsModal -->|"saveCollections() / emit event"| Main
    BreakingChangeModal -->|"acknowledge() / emit event"| Main

    Main -->|"executeSync() / register commands"| SyncService
    SyncService -->|"fetchBookmarks()"| APIService
    APIService -->|"authorize() / refreshToken()"| TokenManager
    APIService -->|"HTTP request"| RaindropAPI
    RaindropAPI -->|"HTTP response"| APIService
    APIService -->|"returnData()"| SyncService
    SyncService -->|"renderTemplate()"| TemplateEngine
    TemplateEngine -->|"load templates"| DefaultTemplate
    TemplateEngine -->|"load metadata templates"| DefaultMetadataTemplate
    TemplateEngine -->|"load html templates"| TemplatesDir
    TemplateEngine -->|"writeFile()"| VaultFS
    Main -->|"saveSettings()"| Settings
    Main -->|"loadTypes()"| Types

    VaultFS -->|"write success/failure"| Main
    Main -->|"storeToken()"| LocalStorage

    %% Click Events
    click Main "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/main.ts"
    click APIService "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/api.ts"
    click TokenManager "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/tokenManager.ts"
    click SyncService "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/sync.ts"
    click TemplateEngine "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/renderer.ts"
    click DefaultTemplate "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/assets/defaultTemplate.njk"
    click DefaultMetadataTemplate "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/assets/defaultMetadataTemplate.njk"
    click TemplatesDir "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/tree/main/src/templates"
    click APITokenModal "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/modal/apiTokenModal.svelte"
    click APITokenModal "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/modal/apiTokenModal.ts"
    click CollectionsModal "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/modal/collections.svelte"
    click CollectionsModal "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/modal/collections.ts"
    click BreakingChangeModal "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/modal/breakingChange.ts"
    click Settings "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/settings.ts"
    click Settings "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/constants.ts"
    click Types "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/types.ts"
    click Types "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/src/custom.d.ts"
    click VaultFS "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/manifest.json"
    click VaultFS "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/package.json"
    click VaultFS "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/esbuild.config.mjs"
    click VaultFS "https://github.com/kaiiiz/obsidian-raindrop-highlights-plugin/blob/main/styles.css"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef core fill:#DFFFE0,stroke:#228B22,stroke-width:2px
    classDef storage fill:#FFF5BA,stroke:#DAA520,stroke-width:2px
    classDef external fill:#FFE8D0,stroke:#D2691E,stroke-width:2px
    classDef asset fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray: 2 2
```
