| # CLAUDE.md |
|
|
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
|
|
| ## Project Overview |
|
|
| QA Annotation System (qa_annotate) - a FastAPI web application for managing and annotating QA dataset pairs. Supports multi-user annotation workflows with role-based access control (superusers manage projects/datasets, regular users perform annotations). |
| |
| ## Commands |
| |
| ```bash |
| # Run dev server |
| uvicorn qa_annotate.main:app --reload --host 0.0.0.0 --port 8000 |
|
|
| # Or via the installed entry point |
| qa |
|
|
| # Create superuser |
| python scripts/create_superuser.py |
| |
| # Lint/format (via pre-commit or directly) |
| ruff check --fix . |
| ruff format . |
| ``` |
| |
| Pre-commit hooks run ruff linting + formatting and standard checks (trailing whitespace, YAML/JSON/TOML validation, etc.). |
| |
| ## Architecture |
| |
| ### Backend (Python/FastAPI) |
| |
| Three-layer architecture inside `qa_annotate/`: |
|
|
| - **`api/`** - FastAPI routers. Each domain has its own module (auth, user, dataset, annotation, project, seed_question, system_config, analysis). All routes are mounted under `/api` prefix. |
| - **`database/`** - SQLAlchemy ORM models (`models.py`) and CRUD operations (`crud.py`). Models use `from_pydantic()` / `to_pydantic()` conversion methods to bridge between SQLAlchemy and Pydantic. DB sessions are provided via `get_db()` generator dependency. |
| - **`schema/`** - Pydantic models for request/response validation. Separate schemas for create, update, and read operations. |
|
|
| Configuration is in `qa_annotate/config.py` using pydantic-settings, reading from `.env` file and environment variables. Key settings: `SECRET_KEY`, `HOST`, `PORT`, `ENVIRONMENT`. |
|
|
| ### Frontend (Vanilla JS) |
|
|
| - **`qa_annotate/html/`** - One HTML file per page (auth, manager, user, annotation, etc.). Pages are served by a catch-all route in `main.py` that maps `/{path}` to `html/{path}.html`. |
| - **`qa_annotate/static/js/`** - One JS file per HTML page, plus shared utilities (`pagination.js`, `project-api.js`). No frontend framework. |
| - **`qa_annotate/static/css/`** - Component-specific stylesheets. |
| - **`qa_annotate/static/locales/`** - i18n translation files. |
|
|
| ### Key Domain Concepts |
|
|
| - **Project** → contains **Datasets** → each dataset contains **QA Pairs** (question + answer + optional extra fields) |
| - **AnnotationConfig** defines annotation task settings (type: score/category/text/multi_choice/single_choice/binary, plus optional reason and confidence fields). Configs are linked to datasets or projects via many-to-many association tables. |
| - **AnnotationResult** stores individual annotation values, linked to a specific QA pair, dataset, config, and annotator. |
| - **SeedQuestion** - predefined question templates organized by type/subtype. |
| - **SystemConfig** - key-value store for system-wide settings. |
|
|
| ### Database |
|
|
| - SQLite only (stored in `data/annotations.db`, configurable via `DB_DIR`/`DB_NAME` settings). |
| - Auto-creates tables on startup via `init_db()`. |
| - Passwords are SHA-256 hashed client-side before storage (see `qa_annotate/utils/password.py`). |
|
|
| ### Auth |
|
|
| JWT-based authentication. Roles: superuser (full access to management pages) vs regular user (annotation tasks only). Token stored in localStorage on the frontend. |
|
|
