GitSyncMarks — Architecture Overview

High-Level Architecture

GitSyncMarks is a browser extension (Manifest V3, Chrome + Firefox) that bidirectionally synchronizes bookmarks with a GitHub repository. It stores each bookmark as an individual JSON file and uses a three-way merge algorithm for conflict-free synchronization.

Component Descriptions

manifest.json / manifest.firefox.json

Extension metadata. Two manifests for browser-specific differences:

Shared: Manifest V3, permissions (bookmarks, storage, alarms, notifications, contextMenus, activeTab, scripting, downloads), host permissions (api.github.com).

background.js — Background Script

The central coordinator:

• Bookmark event listeners — onCreated, onRemoved, onChanged, onMoved trigger debounced auto-sync
• Context menu — contextMenus.onClicked listener (top-level for SW persistence); setupContextMenus() called from onInstalled
• Periodic sync alarm — chrome.alarms for periodic three-way merge sync
• Message handler — Receives sync, push, pull, generateFilesNow, getStatus, switchProfile, settingsChanged, setSettingsSyncPassword, clearSettingsSyncPassword, listDeviceConfigs, importDeviceConfig, getDebugLog from popup/options
• Migration — Checks for and migrates legacy bookmarks.json format on startup

popup.html / popup.js — Popup UI

Toolbar popup with header (icon, title, profile dropdown when 2+ profiles), status area (status line, last change, commit link), conflict box, action buttons (Sync Now, Push, Pull), and compact footer (Settings, GitHub, Report Issue).

options.html / options.js — Settings Page

Full-page settings (opens in tab) with five tabs. Header: language dropdown, theme cycle button (A → Dark → Light → A). All settings auto-save on change; no Save buttons.

1. GitHub (sub-tabs: Profile, Connection, Repos) — Profile selector (multiple profiles with separate repos); token, repository, connection test, onboarding (create folder or pull when path empty/has bookmarks); GitHub Repos folder (optional, position toolbar/other)
2. Sync — Sync profile, auto-sync, sync on start/focus, notifications; Debug Log
3. Files (sub-tabs: Generated, Settings, Export/Import, Git Add) — Generated files (README.md, bookmarks.html, feed.xml, dashy-conf.yml) with Off/Manual/Auto mode; settings sync to Git (Global settings.enc or Individual settings-{id}.enc, with device config import); compact export/import (bookmarks, Dashy, settings plain/encrypted via dropdown); automation guide for adding bookmarks via Git, CLI, or GitHub Actions
4. Help — Quick links (Vote on backlog, Documentation, Discussions, Report Issue) as pill buttons; collapsible feature sections (Getting Started, Profiles, GitHub Repos, Popup, Sync, Files, Notifications, Conflicts, Keyboard Shortcuts)
5. About — Version, links, license, mobile app

lib/sync-engine.js — Sync Engine

Core synchronization with three-way merge:

State is stored as LAST_SYNC_FILES (path → {sha, content}) and LAST_COMMIT_SHA.

lib/github-api.js — GitHub API Wrapper

Wraps both the Contents API (legacy, used for migration/validation) and the Git Data API (for atomic multi-file commits):

lib/bookmark-serializer.js — Serializer

Converts between browser bookmark trees and the per-file format:

lib/crypto.js — Encryption

AES-256-GCM encryption for the GitHub PAT at rest (non-extractable CryptoKey in IndexedDB, token in chrome.storage.local). Also provides password-based encryption (encryptWithPassword / decryptWithPassword using PBKDF2 + AES-256-GCM) for settings export (.enc files) and settings sync to Git.

lib/i18n.js — Internationalization

Custom runtime i18n with manual language selection. Loads _locales/{lang}/messages.json, translates DOM via data-i18n attributes. English fallback.

lib/theme.js — Theme

Light, dark, or auto (system) theme. Single cycle button in options header switches A → Dark → Light → A. Stores preference in chrome.storage.sync, applies html.dark class when dark mode is active. Used by options page and popup.

lib/profile-manager.js — Profile Manager

Multiple bookmark profiles (Work/Personal) with separate GitHub repo config:

State stored in chrome.storage.sync (profiles, activeProfileId) and chrome.storage.local (per-profile tokens, sync state).

lib/onboarding.js — Onboarding

First-time and new-profile setup when configuring GitHub:

lib/github-repos.js — GitHub Repos Folder

Fetches the authenticated user's repos via GitHub REST API and maintains a "GitHubRepos (username)" folder:

lib/remote-fetch.js — Remote File Map

lib/context-menu.js — Context Menu

Right-click menu registered via chrome.contextMenus under a parent "GitSyncMarks" item:

setupContextMenus() is called from onInstalled; handleContextMenuClick() is wired to a top-level contextMenus.onClicked listener for MV3 service worker persistence. refreshProfileMenuItems() rebuilds the profile submenu dynamically — called on install, startup, and whenever profiles or active profile change (via chrome.storage.onChanged listener in background.js).

Favicon source logic: getFaviconUrl(tab) returns tab.favIconUrl if available, otherwise falls back to Google's favicon service (https://www.google.com/s2/favicons?domain={domain}&sz=64).

lib/browser-polyfill.js — Browser Detection

Minimal shim: isFirefox, isChrome, getBrowserName().

File Structure

GitSyncMarks/
├── manifest.json                 # Chrome manifest
├── manifest.firefox.json         # Firefox manifest
├── background.js                 # Background script
├── popup.html / popup.js / popup.css
├── options.html / options.js / options.css
├── lib/
│   ├── sync-engine.js            # Three-way merge sync
│   ├── github-api.js             # GitHub REST + Git Data API
│   ├── bookmark-serializer.js    # Per-file bookmark conversion
│   ├── bookmark-replace.js       # Replace local bookmarks (used by sync + profile switch)
│   ├── github-repos.js          # GitHub Repos folder (user repos as bookmarks)
│   ├── profile-manager.js       # Multiple profiles, switchProfile, migration
│   ├── onboarding.js            # checkPathSetup, initializeRemoteFolder
│   ├── remote-fetch.js           # fetchRemoteFileMap
│   ├── crypto.js                 # Token encryption (AES-256-GCM)
│   ├── context-menu.js            # Right-click context menu (Add, Sync, Favicon)
│   ├── debug-log.js              # Debug log for sync diagnostics
│   ├── i18n.js                   # Internationalization
│   ├── theme.js                  # Light/dark/auto theme (cycle button)
│   └── browser-polyfill.js      # Browser detection
├── _locales/                     # 12 languages (en, de, fr, es, pt_BR, it, ja, zh_CN, ko, ru, tr, pl)
│   ├── en/messages.json
│   ├── de/messages.json
│   └── .../messages.json
├── icons/
├── scripts/
│   ├── build.sh                  # Build Chrome + Firefox packages
│   ├── generate-screenshots.js   # Auto-generate store screenshots (Playwright + Sharp)
│   ├── fetch-app-content.sh      # Fetch App README, assets from GitSyncMarks-App repo
│   ├── build-docs.js             # Markdown → HTML for docs/
│   └── build-index.js            # Build index.html with Extension | App tabs
├── package.json                  # npm scripts for building
├── .github/workflows/
│   ├── test-e2e.yml              # E2E tests (manual trigger only; CI disabled)
│   ├── release.yml               # Build ZIPs, create release on tag
│   ├── screenshots.yml           # Generate store screenshots (manual trigger)
│   └── add-bookmark.yml          # Automation: add bookmark via dispatch
├── docs/                         # Architecture documentation
├── website/                      # GitHub Pages site (index, docs, styles)
├── store-assets/                 # Store listings & screenshots (12 languages)
├── LICENSE
├── PRIVACY.md
└── README.md

Technology Stack