document-parser/CLAUDE.md

Backend — Docling Studio (document-parser)

FastAPI + Python 3.12+ + Docling 2.x + aiosqlite + pytest.

Commandes

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

Architecture (Clean Architecture)

• domain/ — Modèles métier purs, pas de dépendances externes. Dataclasses, value objects, ports abstraits.
• api/ — Couche HTTP : routers FastAPI, schemas Pydantic (DTOs). Sérialisation camelCase via alias_generator.
• services/ — Orchestration des cas d'usage. Relie domain, persistence et infra.
• persistence/ — Repository pattern avec aiosqlite (SQLite). database.py gère connexion et init du schéma.
• infra/ — Adaptateurs : LocalConverter (Docling in-process) et ServeConverter (Docling Serve distant). Settings depuis les variables d'environnement.

Validation pipeline

Exécuter systématiquement avant de considérer une tâche terminée :

.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
.venv/bin/ruff format --check .     # 4. Vérifier zéro diff de format
.venv/bin/pytest tests/ -v          # 5. Tous les tests passent

Tout nouveau code doit avoir des tests. Zéro violation tolérée.

Conventions

• Ruff : rules E, W, F, I (isort), N, UP, B, SIM, TCH, RUF. Line-length 100.
• Exceptions Ruff : E501 ignoré, B008 ignoré (FastAPI Depends), N815 ignoré (camelCase Pydantic), TC003 ignoré (datetime runtime pour Pydantic).
• Imports : isort first-party = api, domain, persistence, services.
• Naming : snake_case partout en Python. camelCase uniquement dans les schemas Pydantic (contrat API).
• Tests : pytest-asyncio avec asyncio_mode = auto. Tests dans tests/.
• Env vars : voir .env.example à la racine. Principales : CORS_ORIGINS, UPLOAD_DIR, DB_PATH.