Installation & Démarrage Local

📋 Prérequis

• Node.js 24 : nvm use lit la version dans .nvmrc, et le package.json racine exige au moins 24.11, première LTS de la branche. Les versions antérieures ne sont pas prises en charge : sous Node 20, l'ingestion décode mal les exports windows-1252 de l'Assemblée, et sous Node 18 sa CLI plante au chargement de undici.
• pnpm 8 (packageManager: pnpm@8.15.0).
• Docker et Docker Compose, pour PostgreSQL et Redis.
• (Facultatif) poppler-utils (commande pdftotext), seulement pour ingérer les comptes rendus de réunion de commission de l'Assemblée, publiés en PDF.

⚡ Installation

Code
git clone https://github.com/accelaire/CLAIR.git
cd CLAIR
pnpm install

# Variables d'environnement : un seul fichier à la racine...
cp .env.example .env
# ...rendu visible depuis les deux paquets qui le lisent. L'API et la CLI
# chargent `.env` depuis leur propre dossier (dotenv), et Prisma lit apps/api/.env.
ln -s ../../.env apps/api/.env
ln -s ../../.env services/ingestion/.env

pnpm docker:up        # PostgreSQL 16 (port 5432) + Redis 7 (port 6379)
pnpm db:generate      # client Prisma
pnpm db:push          # crée le schéma dans la base locale, puis ses triggers
pnpm dev              # web sur :3000, API sur :3001, documentation sur :3002

Les valeurs par défaut de .env.example pointent déjà vers les conteneurs locaux (postgresql://clair:clair_dev@localhost:5432/clair, redis://localhost:6379). Le frontend n'a besoin d'aucune variable en local : NEXT_PUBLIC_API_URL vaut http://localhost:3001 par défaut.

db push et non migrate : l'historique de migrations du dépôt n'est pas rejouable sur une base vierge (la migration 20260313_add_sujets référence une table créée par une migration ultérieure). Pour toute base neuve, locale ou de CI, le schéma s'applique avec db push. Voir Modèle Prisma.

Les triggers ne passent pas par prisma db push, qui ne les connaît pas. pnpm db:push enchaîne donc prisma db push et pnpm db:triggers, qui joue apps/api/prisma/triggers.sql (sans psql, idempotent). Après un prisma db push lancé à la main, rejouer pnpm db:triggers : sans ses triggers, la base ne tient pas updated_at comme la production (voir Suivi des modifications), et check-quality le signale.

Pour ne lancer que la documentation : pnpm dev:docs (port 3002). Elle télécharge la spécification OpenAPI de l'API de production ; sans accès réseau, elle garde la dernière copie téléchargée.

🗃️ Remplir la base

La base est vide après db push. Deux possibilités :

Code
# 1. Jeu de données de test minimal (apps/api/prisma/seed.ts)
pnpm db:seed

# 2. Données réelles, depuis les sources publiques
pnpm --filter @clair/ingestion build     # à faire avant toute synchronisation
pnpm ingestion:smart-sync -a             # tout, dans l'ordre de production

La synchronisation complète écrit des millions de lignes (voir la volumétrie sur la page Modèle Prisma) ; en production, son processus Node tourne avec 6 Go de tas (--max-old-space-size=6144). Pour démarrer plus petit, les commandes sync ciblées acceptent une limite, par exemple pnpm ingestion:sync -p (parlementaires) puis pnpm ingestion:sync -s -l 50 (50 scrutins). Voir Commandes CLI.

Sans MISTRAL_API_KEY, l'enrichissement IA est sauté avec un avertissement ; le reste de la synchronisation fonctionne.

🔍 Vérifier

• Site : http://localhost:3000
• API : http://localhost:3001/health
• Swagger UI de l'API : http://localhost:3001/docs
• Documentation : http://localhost:3002
• Qualité des données : pnpm --filter @clair/ingestion check-quality (voir Qualité des données)