docling-studio/CLAUDE.md

Docling Studio

Plateforme d'analyse documentaire visuelle : upload de PDFs, extraction (texte, tableaux, images, formules, bounding boxes), export Markdown/HTML.

Stack

• Frontend : Vue 3, TypeScript (strict), Vite, Pinia, Vitest
• Backend : FastAPI, Python 3.12+, Docling 2.x, aiosqlite (SQLite), pytest
• Infra : Docker Compose, Nginx (reverse proxy), GitHub Actions CI/CD

Structure

frontend/          # Vue 3 SPA (feature-based: features/{name}/api/, store/, ui/)
document-parser/   # FastAPI backend (Clean Architecture: domain/, api/, persistence/, infra/, services/)
docs/              # MkDocs documentation

Commandes

Backend (depuis document-parser/)

ruff check .              # Lint
ruff check . --fix        # Lint + auto-fix
ruff format .             # Format
pytest tests/ -v          # Tests (199 tests, asyncio_mode=auto)
uvicorn main:app --reload --port 8000  # Dev server

Frontend (depuis frontend/)

npm run lint              # ESLint
npm run lint:fix          # ESLint + auto-fix
npm run format            # Prettier
npm run format:check      # Prettier check
npm run test:run          # Vitest (129 tests)
npm run type-check        # vue-tsc --noEmit
npm run build             # Type-check + build
npm run dev               # Dev server port 3000

Docker

docker compose up         # Dev (frontend + backend)

Git

• Ne jamais push : Claude ne doit jamais exécuter git push.
• Pas de co-auteur : aucune mention de Claude dans les commits (pas de Co-Authored-By, pas de signature).
• Branches : feature/*, fix/*, release/*. PR vers main. Ne jamais empiler de branches sur des branches feature — toujours partir de main.
• Commits : messages concis en anglais, verbe impératif (Fix, Add, Refactor), orientés "why" plutôt que "what".

Validation pipeline

Obligatoire avant de considérer toute tâche terminée. Exécuter dans l'ordre :

Backend (depuis document-parser/)

cd document-parser
.venv/bin/ruff check . --fix        # 1. Lint + auto-fix
.venv/bin/ruff format .             # 2. Format
.venv/bin/ruff check .              # 3. Vérifier zéro violation restante
.venv/bin/ruff format --check .     # 4. Vérifier zéro diff de format
.venv/bin/pytest tests/ -v          # 5. Tous les tests passent

Frontend (depuis frontend/)

cd frontend
PATH="/usr/local/bin:$PATH" npm run lint:fix       # 1. ESLint auto-fix
PATH="/usr/local/bin:$PATH" npm run format         # 2. Prettier format
PATH="/usr/local/bin:$PATH" npm run lint           # 3. Vérifier zéro violation restante
PATH="/usr/local/bin:$PATH" npm run format:check   # 4. Vérifier zéro diff de format
PATH="/usr/local/bin:$PATH" npm run type-check     # 5. vue-tsc --noEmit
PATH="/usr/local/bin:$PATH" npm run test:run       # 6. Tous les tests passent

Critères de validation

• Zéro violation de lint ou format sur les deux projets.
• Tous les tests passent — aucun skip, aucun xfail non justifié.
• Tout nouveau code a des tests — pas de code non couvert dans un commit.
• Si un fichier a été modifié, relancer la pipeline complète du projet concerné (backend, frontend, ou les deux).

Conventions

• API contracts : camelCase (Pydantic alias_generator + frontend). snake_case pour le Python interne.
• Frontend : architecture feature-based, path alias @/ = src/, tests colocalisés (*.test.ts).
• Backend : Clean Architecture — domain pur (pas de dépendances externes), repository pattern, ports abstraits, converters pluggables (local/remote). Imports first-party : api, domain, persistence, services.
• Linting : Ruff (backend, line-length 100), ESLint 9 flat config + Prettier (frontend, 100 chars, sans semicolons, single quotes).
• Tests : toujours lancer les tests et le lint avant de considérer une tâche terminée (voir section Validation pipeline ci-dessus).
• Pas de fichiers inutiles : préférer modifier l'existant plutôt que créer de nouveaux fichiers.
• Voir aussi : CONTRIBUTING.md pour le guide de contribution complet.