myworkspace/LinkSyncServer/AGENTS.md

AGENTS.md - LinkSyncServer

Project Overview

LinkSyncServer is a self-hosted bookmark server with advanced collection and query capabilities. It provides a RESTful API and web interface for managing bookmarks (links), collections (static or dynamic sets), and supports synchronization with browser extensions.

Setup & Build Commands

• Build: docker-compose up -d --build
• Test: pytest tests/ -v
• Lint: ruff check . && mypy app.py models/
• Dev: docker-compose up web
• Migrate: alembic upgrade head

Architecture Notes

Core Components

1. Authentication Layer: JWT-based auth with admin/regular user roles
2. Link Management: CRUD for links with all Firefox bookmark fields
3. Collection Engine: Static and dynamic collections with query support
4. Query Parser: Expression parser supporting AND/OR/XOR set operations
5. Sync Protocol: Extension sync endpoint with conflict resolution

Data Models

• User: Authentication and authorization
• Link: Bookmark with all Firefox fields
• Collection: Static or dynamic set of links
• Tag: Optional categorization
• AuditLog: Track changes

Query Engine

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

• Precedence: () > XOR > AND > OR
• Left-to-right evaluation otherwise
• Full-text search via PostgreSQL tsvector

Testing Protocol

• All tests must pass before committing
• Run pytest tests/ -v for full test suite
• Coverage target: >80%
• E2E tests cover critical user flows

Conventions

File Naming

• Models: {entity}.py in models/ directory
• Endpoints: endpoints/{resource}.py
• Queries: queries/{operation}.py

Error Handling

• Use HTTP status codes appropriately
• Return structured error responses
• Log errors with stack traces in debug mode

API Design

• RESTful conventions
• JSON responses with Content-Type
• Paginated lists with limit/offset
• OpenAPI documentation via @openapi

Database

• UUID primary keys
• Timestamps on all records
• Foreign keys with cascade delete where appropriate
• Full-text search indexes on searchable fields

Known Issues / Technical Debt

• None at initialization
• Query engine performance to be optimized
• Caching layer to be implemented

Project-Specific Tools

• Query Parser: queries/parser.py
• Query Executor: queries/executor.py
• Sync Logic: api/endpoints/sync.py

Related Files

• README.md - Overview and quick start
• design.md - Architecture and API details
• tasks.md - Implementation checklist
• docker-compose.yml - Deployment configuration

Admin User Creation

Admin user is created from environment variables:

• ADMIN_USERNAME
• ADMIN_PASSWORD
• SECRET_KEY (generate securely)

Admin can create:

• Regular users
• Admin users
• API keys
• System settings

Security Notes

• Never commit .env files
• Use strong passwords
• Rotate SECRET_KEY periodically
• Enable HTTPS in production