---
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)

```json
{
  "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

```json
{
  "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:

```json
{
  "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.