myworkspace/LinkSyncServer/tasks.md

LinkSyncServer - Implementation Tasks

Phase 1: Project Setup

Setup Tasks

• Initialize git repository
• Configure git remote (gitea.blabber1565.com)
• Create directory structure
• Write README.md
• Write TODOs.txt
• Write design.md
• Write tasks.md
• Write AGENTS.md
• Create docker-compose.yml
• Create Dockerfile
• Create requirements.txt
• Create pyproject.toml
• Create .env.example

Phase 2: Core Application

App Configuration

• Create app.py with FastAPI setup
• Configure CORS
• Set up error handlers
• Create health check endpoint
• Create config/settings.py

Database Setup

• Create models/base.py
• Create models/user.py
• Create models/link.py
• Create models/collection.py
• Create models/tag.py
• Create models/audit_log.py
• Configure SQLAlchemy engine
• Create schema.sql
• Set up Alembic migrations

Authentication

• Create models for users/roles
• Implement password hashing (bcrypt)
• Create JWT token utilities
• Implement login endpoint
• Implement register endpoint
• Implement logout endpoint
• Create API key model and endpoints
• Set up session management

Phase 3: API Endpoints

Auth Endpoints

• POST /api/auth/register/
• POST /api/auth/login/
• POST /api/auth/logout/
• POST /api/auth/api-key/
• DELETE /api/auth/api-key/{key_id}/

Link Endpoints

• GET /api/links/ - list with pagination and filters
• GET /api/links/{id}/ - single link details
• POST /api/links/ - create link
• PUT /api/links/{id}/ - update link
• DELETE /api/links/{id}/ - delete link
• POST /api/links/{id}/tags/ - add tags
• DELETE /api/links/{id}/tags/ - remove tags

Collection Endpoints

• GET /api/collections/ - list collections
• GET /api/collections/{id}/ - collection details
• POST /api/collections/ - create collection
• PUT /api/collections/{id}/ - update collection
• DELETE /api/collections/{id}/ - delete collection
• POST /api/collections/{id}/refresh/ - refresh dynamic collection
• POST /api/collections/{id}/add-links - add links to static collection
• DELETE /api/collections/{id}/remove-links - remove links from collection

Query Endpoints

• POST /api/queries/parse/ - parse and validate query
• POST /api/queries/execute/ - execute query and return results
• GET /api/queries/{id}/ - get saved query

Sync Endpoint

• POST /api/sync/ - sync with browser extension
• Implement sync mode logic
• Handle conflict resolution
• Process deletions

Admin Endpoints

• GET /api/admin/users/ - list all users
• POST /api/admin/users/ - create user
• PUT /api/admin/users/{id}/ - update user
• DELETE /api/admin/users/{id}/ - delete user
• GET /api/admin/stats/ - system statistics
• GET /api/admin/audit/ - audit log

Phase 4: Query Engine

Parser

• Create tokenization logic
• Implement AST node classes
• Build parser with precedence rules
• Validate AST
• Serialize AST to JSON

Executor

• Implement TermSet executor
• Implement TagFilter executor
• Implement FieldFilter executor
• Implement AND/OR/XOR operators
• Build SQL from AST
• Execute queries with full-text search

Phase 5: Web Interface

Layout

• Create templates/base.html
• Create templates/index.html
• Create navigation component
• Create CSS main.css

Static Files

• Create static/css/main.css
• Create static/js/main.js

Phase 6: Testing

Unit Tests

• tests/test_auth.py
• tests/test_links.py
• tests/test_collections.py
• tests/test_queries.py

Integration Tests

• Setup test database
• Test full registration flow
• Test CRUD operations
• Test sync endpoint
• Test query execution

Phase 7: Docker & Deployment

Docker

• Create optimized Dockerfile
• Configure health checks
• Test container build
• Test container run
• Test docker-compose

Phase 8: Documentation

• API reference (via OpenAPI/Swagger)
• User guide (README.md)
• Query syntax guide (README.md)
• Deployment guide (README.md)

Phase 9: Web Interface Enhancements

Session Management

• Token expiry detection on page load
• 401 interceptor for all API calls
• Session expiry warning banner (<2 minutes)
• Graceful redirect to login on expiry
• Session expired message on login page

Dashboard

• Stats display with numbers (never -)
• Quick actions grid
• Admin section visibility toggle
• Resilient stats loading (allSettled pattern)

Links Page

• Simple search mode (keyword across all fields)
• Query mode toggle (set operations)
• Multi-word AND search
• Tag search inclusion
• Save as Collection feature (static and dynamic)
• Query preview with result count

Collections Page

• Query builder UI for dynamic collections
• Query preview button
• Result count display
• Query expression display on cards
• Type selector toggles query section

API Keys Page

• Create API key modal
• Delete API key confirmation

Admin Page

• User CRUD interface
• Role assignment
• System statistics
• Audit log viewer

Phase 10: Testing

E2E Tests (Playwright)

• Install Playwright and pytest-playwright
• Auth flow tests (login, dashboard, logout, expiry)
• Link CRUD tests
• Search tests (simple, multi-word, by tag, query mode)
• Collection tests (static, dynamic with query, delete)
• Save as Collection tests (static and dynamic)
• API Key tests (create, delete)
• Admin tests (user management)