Initial commit of MyWorkspace - contains multiple projects and global workspace configuration
This commit is contained in:
DavidSaylor
255
Linkding Browser Extension/docs/DESIGN.md
Normal file
255
Linkding Browser Extension/docs/DESIGN.md
Normal file
@@ -0,0 +1,255 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user