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

```yaml
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

```bash
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.