# 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`
- **E2E Test**: `pytest tests/test_e2e.py -v --browser chromium`
- **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 (84+ unit/integration tests)
- Run `pytest tests/test_e2e.py -v --browser chromium` for E2E tests (20+ tests)
- Coverage target: >80%
- E2E tests cover critical user flows:
  - Login, dashboard stats, session expiry
  - Link CRUD, search (simple, multi-word, query mode)
  - Collection CRUD, query builder, save as collection
  - API key management, admin user management

## Web Interface Requirements

### Session Management
- Token expiry detection on page load (decode JWT `exp` claim)
- 401 interceptor redirects to login on authentication failure
- Session expiry warning banner when token expires in <2 minutes
- Graceful logout clears storage and redirects to login
- Login page shows expiry message when redirected with `?expired=1`

### Dashboard
- Stats display always shows numbers (0, never `-`)
- Quick actions for creating links, collections, API keys
- Admin section visible only to admin users
- Resilient loading (allSettled pattern - one failing API doesn't break others)

### Links Page
- **Simple search mode**: Keyword search across title, URL, description, notes, and tags
- **Query mode**: Full set operations (AND, OR, XOR, NOT, parentheses, field filters)
- Multi-word search uses AND logic (all terms must match)
- Tags are included in all searches
- **Save as Collection**: Convert current results to static collection or query to dynamic collection

### Collections Page
- Static collections: Manual link management
- Dynamic collections: Query expression with preview
  - Query builder UI with syntax hints
  - Preview button shows matching links and count
  - Query expression displayed on collection cards

### Error Handling
- API errors return structured responses with user-friendly messages
- Form validation before submission
- Network errors show graceful fallbacks

## 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