myworkspace/LinkSyncServer/README.md

LinkSyncServer

A self-hosted bookmark server with advanced collection and query capabilities, designed to work with browser extensions for bookmark synchronization.

Overview

LinkSyncServer replaces the need for workarounds in existing bookmark sync solutions. It provides:

• True Collections - First-class collection objects with saved queries
• Advanced Query Engine - Supports AND, OR, XOR set operations
• Firefox-Compatible Fields - All bookmark attributes natively supported
• Multi-User Support - Authentication with admin and regular user roles
• RESTful API - Full CRUD operations for links and collections
• Web Interface - Modern UI for browsing, searching, and managing collections
• Docker-Ready - Easy deployment with Docker Compose

Features

Collections

Two types of collections:

Type	Description
Static	Explicit set of link IDs
Dynamic	Query expression evaluated on each access

Dynamic Collection Query Syntax

('term1', 'term2', 'term3') OR tagA AND tagB XOR url:example.com

• Parentheses evaluated first (innermost to outermost)
• Left-to-right evaluation otherwise
• Precedence: () > XOR > AND > OR

Set Operations

Query builder supports visual set operations:

Set1 AND Set2 XOR Set3 OR Set4

This evaluates as: (((Set1 AND Set2) XOR Set3) OR Set4)

Synchronization Modes

Mode	Browser → Server	Server → Browser
Bi-directional	Add/update	Add/update
Browser Authoritative	Add/update	Overwrite
Server Authoritative	Download only	Overwrite

Optional: Enable deletions for all modes.

Bookmarks (Links)

All Firefox bookmark attributes supported:

• id - Unique identifier
• url - Bookmark URL (duplicates allowed)
• title - Display title
• description - Optional description
• notes - User notes
• tags - Array of tag names
• favicon_url - Icon URL
• path - Folder structure
• created_at, updated_at - Timestamps
• visit_count - Number of visits
• is_bookmarked - Bookmarked status
• source_set_id - Collection that added this link

Architecture

┌─────────────────────────────────────┐
│         LinkSyncServer              │
│                                     │
│  ┌──────────────┐  ┌─────────────┐ │
│  │   API Layer  │  │   Auth      │ │
│  └──────────────┘  └─────────────┘ │
│  ┌──────────────┐  ┌─────────────┐ │
│  │   Query      │  │   Models    │ │
│  │   Engine     │  │   (SQLAlchemy)│ │
│  └──────────────┘  └─────────────┘ │
│  ┌──────────────┐  ┌─────────────┐ │
│  │   Templates  │  │   Static    │ │
│  └──────────────┘  │   Files     │ │
│  ┌──────────────┐  └─────────────┘ │
│  │   PostgreSQL │                 │ │
│  │               │                 │ │
│  └──────────────┘                 │ │
└─────────────────────────────────────┘

Quick Start

Prerequisites

• Docker and Docker Compose
• Port 5000 available (or configurable)

Docker Compose

version: '3.8'

services:
  web:
    build: .
    ports:
      - "5000:5000"
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/linksync
      - SECRET_KEY=your-secret-key-here
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=admin123
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=linksync
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - linkdata:/var/lib/postgresql/data

volumes:
  linkdata:

Build and Run

docker-compose up -d --build

Initial Login

• URL: http://localhost:5000
• Admin credentials from environment variables
• Create first admin account
• Admin can create regular users and admin users

API Documentation

See /api/docs or /api/openapi.json for complete API specification.

Configuration

Environment variables:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
SECRET_KEY	JWT secret key	Required
ADMIN_USERNAME	Initial admin username	-
ADMIN_PASSWORD	Initial admin password	-
DEBUG	Debug mode	False
HOST	Bind address	0.0.0.0
PORT	Port	5000

Project Structure

LinkSyncServer/
├── README.md
├── TODOs.txt
├── design.md
├── tasks.md
├── AGENTS.md
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── app.py
├── config/
├── api/
├── models/
├── queries/
├── templates/
└── static/

License

MIT License

Support

For issues and feature requests, see the GitHub repository.