# 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