# frederikb/bookmarksync architecture

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

- Interactive diagram: https://gitdiagram.com/frederikb/bookmarksync
- Repository: https://github.com/frederikb/bookmarksync

## Overview

##### Project Type and Purpose
- This is a browser extension (built with Web Extension Toolkit) that synchronizes browser bookmarks from JSON files stored in a GitHub (or GHES) repository.
- It comprises a background service worker that handles scheduling and syncing logic, two UI entrypoints (Options page and Popup), utility modules for GitHub interaction and bookmark processing, and relies on browser APIs (bookmarks, storage, notifications).

##### Main Components
a. Extension UIs (Frontend)
- Options Page (HTML/CSS/JS)
- Popup Page (HTML/CSS/JS)
b. Background Service Worker
- Entry: src/entrypoints/background.js
- Handles alarms, manual sync triggers, and coordination of modules
c. Utility Modules
- GitHub loader (src/utils/github-bookmarks-loader.js / Octokit)
- Bookmark parser & validator (src/utils/bookmarksync.js + JSON schema)
- Options storage (src/utils/options-storage.js)
- Error handling (src/utils/errors.js)
d. Browser APIs
- browser.storage (storing token, repo, path)
- browser.alarms (scheduling)
- browser.bookmarks (reading/updating bookmarks)
- browser.notifications (user feedback)
e. External Service
- GitHub or GitHub Enterprise API (via configurable API URL + PAT)
f. Static Assets
- Schema file (src/utils/bookmarks.1-0-0.schema.json)

##### Relationships and Data Flows
- At startup or on alarm → Background Worker reads config from browser.storage → calls GitHub API → fetches one or more JSON files → validates against schema → computes delta vs. existing bookmarks (browser.bookmarks) → writes new/updated bookmarks → fires browser.notifications
- Popup UI → sends a “manual sync” message to Background via runtime messaging → triggers immediate sync workflow
- Options UI → reads/saves user configuration to browser.storage via Options Storage module
- All components are bundled by wxt.config.ts and loaded per manifest definitions

##### Architectural Patterns & Design Principles
- Event-driven: browser.alarms and runtime messaging trigger actions
- Modular: clear separation between UI entrypoints, background orchestration, utility modules
- Single responsibility: each utils file handles one concern (storage, GitHub fetch, parsing, errors)
- External integration: Octokit for GitHub, JSON Schema for validation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Entrypoints
    subgraph "UI Entrypoints"
        style UI fill:none,stroke:none
        OptionsPage["Options Page"]:::ui
        PopupPage["Popup Page"]:::ui
    end

    %% Background Worker
    Background["Background Service Worker"]:::background

    %% Utilities
    subgraph "Utilities"
        style Utils fill:none,stroke:none
        GitHubLoader["GitHub Bookmarks Loader"]:::utils
        Bookmarksync["Bookmark Parser & Validator"]:::utils
        Schema["JSON Schema (1.0.0)"]:::utils
        OptionsStorage["Options Storage"]:::utils
        ErrorHandling["Error Handling"]:::utils
    end

    %% Browser APIs & Storage
    subgraph "Browser APIs & Storage"
        style APIs fill:none,stroke:none
        StorageDB["Browser Storage"]:::storage
        BookmarksDB["Browser Bookmarks"]:::db
        Alarms["browser.alarms"]:::api
        Notifications["browser.notifications"]:::api
        RuntimeMsg["browser.runtime messaging"]:::api
    end

    %% External Service
    GitHubAPI["GitHub API"]:::external

    %% Connections
    OptionsPage -->|"save/read config"| StorageDB
    PopupPage -->|"send sync message"| RuntimeMsg
    RuntimeMsg -->|"onMessage: sync now"| Background
    Alarms -->|"onAlarm"| Background
    Background -->|"get config"| StorageDB
    Background -->|"fetch bookmarks JSON"| GitHubLoader
    GitHubLoader -->|"for each file"| GitHubAPI
    GitHubLoader -->|"raw JSON payload"| Bookmarksync
    Schema -->|"validate JSON"| Bookmarksync
    Bookmarksync -->|"validated bookmark data"| Background
    Background -->|"create/update"| BookmarksDB
    Background -->|"notify user"| Notifications
    Background -->|"handle errors"| ErrorHandling
    Background -->|"use options API"| OptionsStorage

    %% External requests
    Background -->|"HTTP GET /repos/... "| GitHubAPI

    %% Click Events
    click OptionsPage "https://github.com/frederikb/bookmarksync/tree/main/src/entrypoints/options"
    click PopupPage "https://github.com/frederikb/bookmarksync/tree/main/src/entrypoints/popup"
    click Background "https://github.com/frederikb/bookmarksync/blob/main/src/entrypoints/background.js"
    click GitHubLoader "https://github.com/frederikb/bookmarksync/blob/main/src/utils/github-bookmarks-loader.js"
    click Bookmarksync "https://github.com/frederikb/bookmarksync/blob/main/src/utils/bookmarksync.js"
    click Schema "https://github.com/frederikb/bookmarksync/blob/main/src/utils/bookmarks.1-0-0.schema.json"
    click OptionsStorage "https://github.com/frederikb/bookmarksync/blob/main/src/utils/options-storage.js"
    click ErrorHandling "https://github.com/frederikb/bookmarksync/blob/main/src/utils/errors.js"
    click GitHubAPI "https://github.com/frederikb/bookmarksync/blob/main/wxt.config.ts"
    
    %% Styles
    classDef ui fill:#bbdefb,stroke:#0d47a1,color:#0d47a1,stroke-width:1px
    classDef background fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20,stroke-width:1px
    classDef utils fill:#fff9c4,stroke:#f57f17,color:#f57f17,stroke-width:1px
    classDef storage fill:#ffe0b2,stroke:#e65100,color:#e65100,stroke-width:1px
    classDef db fill:#ffecb3,stroke:#bf360c,color:#bf360c,stroke-width:1px
    classDef api fill:#b2dfdb,stroke:#00695c,color:#00695c,stroke-width:1px
    classDef external fill:#e1bee7,stroke:#4a148c,color:#4a148c,stroke-width:1px
```
