document-parser/CLAUDE.md

# Backend — Docling Studio (document-parser)

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

## Commandes

```bash
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 :**

```bash
.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`.