Guide Développeur

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 12.15 (packageManager: pnpm@12.15.0) : corepack enable une fois, puis corepack fournit la version du dépôt à chaque appel de pnpm. Le package.json racine exige au moins pnpm 12.15 (engines).
  • 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

TerminalCode
git clone https://github.com/accelaire/CLAIR.git cd CLAIR corepack enable # une fois : pnpm à la version de packageManager pnpm install # installe aussi les hooks git (lefthook : Biome et commitlint) # 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 # tout : web :3000, API :3001, doc :3002, nouveau site :3010, Storybook :3050

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 qu'une partie :

TerminalCode
pnpm dev:api # API seule (port 3001) pnpm --filter @clair/site dev # nouveau site (port 3010), branché sur l'API locale pnpm storybook # atelier des composants (port 3050), sans API pnpm dev:docs # documentation (port 3002)

La documentation 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 :

TerminalCode
# 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