Plateforme & Guide

Stack Technique & Dépendances

Versions : plage déclarée dans les package.json, et entre parenthèses la version résolue dans pnpm-lock.yaml lorsqu'elle diffère utilement. Le nouveau front épingle ses versions exactement dans le catalog de pnpm-workspace.yaml.

🧱 Commun

  • Runtime : Node.js 24 (.nvmrc ; au moins 24.11 selon les engines du package.json racine). La CI lit .nvmrc, les images Docker partent de node:24-alpine, et le site comme la documentation déclarent 24.x à Vercel.
  • Langage : TypeScript 5 (5.9.3) pour l'existant, TypeScript 6.0.3 pour le nouveau front (catalog).
  • Gestionnaire de paquets : pnpm 12.15, une seule version lue partout dans packageManager (pnpm@12.15.0) : en local par corepack, en CI par pnpm/action-setup, dans les images Docker par corepack enable. Réglages dans pnpm-workspace.yaml (catalog, hoistPattern, packageExtensions, allowBuilds, minimumReleaseAgeExclude).
  • Monorepo : pnpm workspaces + Turborepo 2.
  • Tests : Vitest 1 (API et ingestion), Vitest 5 + Testing Library + happy-dom (packages du nouveau front), Storybook 10 + Vitest navigateur (stories et accessibilité), Playwright 1.64 + axe (parcours du site et de la documentation). Côté apps/web, seul le proxy /api/v1 est testé (Vitest 1).
  • Qualité du code : Biome 2 pour le nouveau front et l'outillage récent (pnpm check) ; ESLint 8 et Prettier 3 pour l'existant (pnpm lint, pnpm format) ; lefthook (hooks git) et commitlint (Conventional Commits).
  • Logs : pino 8.

⚡ API (apps/api)

  • Framework : Fastify 4 (4.29.1), avec @fastify/compress, @fastify/cors, @fastify/helmet, @fastify/rate-limit, @fastify/swagger et @fastify/swagger-ui.
  • ORM : Prisma 5 (5.22.0).
  • Validation : Zod 3.
  • Cache et limitation de débit : Redis, via ioredis.
  • Recherche : requêtes PostgreSQL par Prisma (contains, insensible à la casse), puis classement applicatif par similarité Jaro-Winkler (apps/api/src/utils/fuzzy-search.ts). Aucun moteur de recherche dédié.

🧭 Nouveau site (apps/site et packages/*)

  • Framework : Next.js 16.4 (App Router), React 19.3.
  • Interface : Mantine 9.7 (@mantine/core, charts, dates, hooks), thémée par @clair/theme (tokens --clair-*) ; CSS modules, pas de Tailwind.
  • Paquets : @clair/theme (tokens et thème), @clair/ui (composants), @clair/data (types des réponses de l'API, écrits à la main), @clair/api-client (client HTTP et TanStack Query 5), @clair/screens (un dossier par écran), @clair/config (tsconfig et Vitest partagés).
  • Atelier : Storybook 10 (apps/storybook).
  • Graphiques et icônes : Recharts 3, lucide-react 1.

Détail : Front.

💻 Site actuel (apps/web)

  • Framework : Next.js 14.0.4 (App Router), React 18.
  • Styles : Tailwind CSS 3, class-variance-authority, tailwind-merge, tailwindcss-animate, thème clair et sombre avec next-themes.
  • Données : TanStack Query 5 ; les appels du navigateur passent par un proxy Next (app/api/v1/[...path]/route.ts) qui relaie vers l'API.
  • Graphiques : Recharts 2.
  • Icônes et animations : lucide-react, framer-motion.
  • Mesure d'audience : Plausible (sans cookie).

📥 Ingestion (services/ingestion)

  • CLI : commander 11.
  • Téléchargement et lecture : axios, cheerio (HTML), xml2js (XML), csv-parse (CSV), tar-stream (archives de la base LEGI), lecteur XLSX maison (src/utils/xlsx.ts), pdftotext de poppler-utils pour les comptes rendus de commission publiés en PDF.
  • Concurrence : p-limit, limiter.
  • Références juridiques : @tricoteuses/tisseuse (AGPL-3.0, comme CLAIR) repère les textes et articles de loi cités dans le dispositif des amendements ; la résolution vers Légifrance passe par notre index de la base LEGI.
  • Build : tsup (CJS + ESM) ; exécution en développement avec tsx.
  • IA : API Mistral (mistral-small-latest pour la génération, mistral-embed pour le classement des liens de contexte), Tavily (recherche ciblée sur vie-publique.fr).

📚 Documentation (docs)

  • Portail : Zudoku 0.93 ; recherche plein texte par Pagefind. Le thème et les aperçus de composants lisent @clair/theme et @clair/ui.
  • Référence de l'API : la spécification OpenAPI générée par l'API de production (https://api.clair.vote/docs/json), téléchargée à chaque build dans docs/public/openapi.json (fichier ignoré par git).

🌐 Infrastructure

ÉlémentDéveloppement localProduction
PostgreSQL16 (postgres:16-alpine, docker-compose.yml)17 (image Railway postgres-ssl:17)
Redis7 (redis:7-alpine)8.2.1
Site actuel (apps/web)next dev sur le port 3000Vercel, région cdg1 (Paris)
Nouveau site (apps/site)next dev sur le port 3010beta.clair.vote pendant la migration
Storybookstorybook dev sur le port 3050
APItsx watch sur le port 3001Railway, image construite depuis le Dockerfile racine
Documentationzudoku dev sur le port 3002Vercel (docs.clair.vote)
IngestionCLI lancée à la mainRailway, deux services planifiés (voir Déploiement)
CIGitHub Actions : ESLint et tests de l'existant, Biome, types, tests, stories et e2e du nouveau front, build ; fragments du journal des versions (voir Déploiement)