Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation

2026-05-11 17:37:10 -05:00
parent ad0b12b452
commit aed69afdfd
691 changed files with 181874 additions and 28 deletions
--- a/LinkSyncServer/README.md
+++ b/LinkSyncServer/README.md
@@ -0,0 +1,194 @@
+# 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.