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 lesenginesdupackage.jsonracine). La CI lit.nvmrc, les images Docker partent denode:24-alpine, et le site comme la documentation déclarent24.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 parpnpm/action-setup, dans les images Docker parcorepack enable. Réglages danspnpm-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/v1est 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/swaggeret@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 avecnext-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),pdftotextde 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-latestpour la génération,mistral-embedpour 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/themeet@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 dansdocs/public/openapi.json(fichier ignoré par git).
🌐 Infrastructure
| Élément | Développement local | Production |
|---|---|---|
| PostgreSQL | 16 (postgres:16-alpine, docker-compose.yml) | 17 (image Railway postgres-ssl:17) |
| Redis | 7 (redis:7-alpine) | 8.2.1 |
Site actuel (apps/web) | next dev sur le port 3000 | Vercel, région cdg1 (Paris) |
Nouveau site (apps/site) | next dev sur le port 3010 | beta.clair.vote pendant la migration |
| Storybook | storybook dev sur le port 3050 | |
| API | tsx watch sur le port 3001 | Railway, image construite depuis le Dockerfile racine |
| Documentation | zudoku dev sur le port 3002 | Vercel (docs.clair.vote) |
| Ingestion | CLI lancée à la main | Railway, deux services planifiés (voir Déploiement) |
| CI | GitHub 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) |