113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# 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 |