myworkspace/Linkding Browser Extension/docs/DESIGN.md

title

title
LinkdingSync - Design Document

LinkdingSync Extension Design Document

Overview

linkdingsync is a Firefox browser extension that synchronizes bookmarks with a self-hosted Linkding instance. It supports folder hierarchy, bidirectional sync, and configurable sync modes for different use cases (personal, work, shared bundles).

Project Location

MyWorkspace/Linkding Browser Extension/bookmark-sync/

Extension Name

linkdingsync - Firefox extension name (manifest.json)

---

1. Data Storage Structure

config.json (stored in web storage)

{
  "serverUrl": "https://links.blabber1565.com/api",
  "apiKey": "your-api-token-here",
  "bundleId": null,
  "bundleName": null,
  "syncMode": "bi-directional",
  "autoGenerateTags": false,
  "syncTimestamp": "2026-05-06T04:38:26-05:00"
}

Storage Areas

• window.storage.local - Persistent data per browser profile
• window.storage.session - Temporary session data

Stored Data Structure

{
  "serverUrl": "https://links.blabber1565.com/api",
  "apiKey": "your-api-token-here",
  "bundleId": 5,
  "bundleName": "My Browser Bundle",
  "syncMode": "bi-directional",
  "autoGenerateTags": false,
  "lastSyncTimestamp": 1715012345678,
  "bookmarksVersion": 1234567890
}

Sync Mode Values

Value	Description	Conflict Resolution
bi-directional	Replicate both directions; keep both versions	Keep both versions
write-only	Browser is authoritative source	Update Linkding from browser
read-only	Linkding is authoritative source	Download from Linkding, never upload

Default: bi-directional

---

2. Bookmark Notes Structure

The notes field uses a JSON-compatible structure that remains human-readable:

{
  "path": "Work/Resources/Development",
  "userNotes": "Development resources and references",
  "autoTags": [
    {"name": "Work"},
    {"name": "Resources"},
    {"name": "Development"}
  ]
}

Display Format

• Only show userNotes in the UI
• path and autoTags are hidden from regular users

Auto-generate Tags Setting

• Default: false (disabled)
• When true, extracts folder names from path as tag suggestions
• User must organize folders intentionally for tag auto-generation to work correctly

---

3. Bundle Naming

• User-defined bundle names via config UI
• Examples: "My Personal Bookmarks", "Work Resources", "Project Collection"
• Extension prompts for missing config (server URL, API key, bundle selection) on first run

---

4. Extension File Structure

bookmark-sync/
├── manifest.json              # Firefox manifest v2
├── popup.html                 # Main extension popup
├── popup.css                  # Popup styling
├── popup.js                   # Popup UI logic
├── background.html            # Settings/config page
├── background.js              # Service worker
├── storage.js                 # Web storage helpers
├── utils/
│   ├── bookmark.js            # Bookmark manipulation
│   ├── notes-parser.js        # Parse/write notes structure
│   ├── sync.js                # Sync logic (add, delete, update)
│   └── conflict-resolver.js   # Handle sync conflicts
└── icons/
    ├── 48.svg                 # 48x48 icon
    └── 96.svg                 # 96x96 icon

---

5. Key Features

Popup UI

• Quick bookmark add with optional notes
• Sync status indicator
• Settings button → opens config page

Config Page (background.html)

• Server URL input (default: links.blabber1565.com)
• API key input (with "Get from Linkding Settings" guidance)
• Bundle selection dropdown (with "Create new bundle" button)
• Sync mode selector (bi-directional | write-only | read-only)
• Auto-generate tags toggle
• Sync last timestamp (human-readable with timezone)
• Manual sync button
• Reset config button

Background Service

• Monitor bookmark events (add, remove, modify)
• Perform sync operations with Linkding API
• Cache recent API responses
• Handle errors and show notifications

---

6. Sync Logic Flow

1. Browser bookmark change detected
   ↓
2. Check syncMode:
   - read-only: download from Linkding only
   - write-only: sync to Linkding only
   - bi-directional: sync both directions
   ↓
3. For updates (same URL, different folder):
   - Store both versions with different notes
   - User must manually de-dupe later
   ↓
4. For new bookmarks:
   - Check if URL already in Linkding
   - If no → create new bookmark
   - If yes + different URL → create new bookmark
   - If yes + same URL → update title, description, notes
   ↓
5. For deletions:
   - write-only → delete from Linkding
   - read-only → ignore (keep Linkding version)
   - bi-directional → delete from Linkding

---

7. API Endpoints Used

Authentication

Authorization: Token <Token>

Bookmarks

• GET /api/bookmarks/ - List bookmarks
• POST /api/bookmarks/ - Create bookmark
• PUT/PATCH /api/bookmarks/<id>/ - Update bookmark
• DELETE /api/bookmarks/<id>/ - Delete bookmark
• GET /api/bookmarks/check/?url=... - Check if URL is already bookmarked

Bundles

• GET /api/bundles/ - List bundles
• POST /api/bundles/ - Create bundle
• PUT/PATCH /api/bundles/<id>/ - Update bundle
• DELETE /api/bundles/<id>/ - Delete bundle

---

8. Implementation Plan

Phase 1: Core Setup

• Create manifest.json
• Create popup HTML/CSS/JS
• Create background service worker
• Implement storage.js helpers

Phase 2: Sync Logic

• Implement bookmark manipulation (bookmark.js)
• Implement notes parser (notes-parser.js)
• Implement sync logic (sync.js)
• Implement conflict resolution (conflict-resolver.js)

Phase 3: Configuration UI

• Create config page (background.html)
• Implement config form logic
• Add API key guidance

Phase 4: Polish

• Add icons
• Add error handling
• Add notifications
• Test sync scenarios

---

9. Resource Storage Location

All downloaded resources should be stored in MyWorkspace folder to avoid permission prompts:

MyWorkspace/Linkding Browser Extension/
├── bookmark-sync/          # Main extension directory
├── linkding/               # Cloned repo (if needed)
├── linkding-extension/     # Existing extension (if needed)
└── assets/                 # Cached icons, screenshots

---

10. Version History

Version	Date	Changes
0.1.0	2026-05-06	Initial design document

---

11. Notes

This document should be referenced during implementation to ensure all requirements are met. Any deviations from this design should be documented here.