siop2/docs/03-architecture/adr/ADR-001-stack.md

ADR-001 — Stack technique

• Statut : acceptée (R0, 15 juillet 2026)
• Contexte : la V2 repart de zéro (code) mais pas de nulle part : la v1 a éprouvé une stack pendant 8 sprints (~400 tests). Atlas CMMS, notre référence fonctionnelle, est en Java Spring Boot + React MUI — cloner sa stack n'a aucun intérêt pédagogique ni pratique pour une équipe TypeScript.

Décision

Couche	Choix	Justification
Monorepo	pnpm workspaces + Turborepo	Un dépôt, plusieurs apps, caches de tâches ; éprouvé v1
API	NestJS (Node 24) + Prisma + PostgreSQL 18	Architecture modulaire enseignable ; Prisma = modèle lisible par les étudiants
Extensions BDD	pgvector (RAG, R5) + PostGIS (carte, R1)	Un seul moteur de données pour tout
Cache/files	Redis (BullMQ pour les jobs, R2)	Génération mensuelle du préventif
Fichiers	MinIO derrière l'interface FileStorage	S3-compatible auto-hébergé ; l'interface interdit tout couplage (règle lint)
Contrat	Zod → OpenAPI → clients typés (« règle d'or »)	Le front ne peut pas dériver du back ; CI bloquante
Web	React 19 + Vite + TanStack Query/Table + Tailwind v4	Éprouvé v1
UI kit	shadcn/ui thématisé par docs/02-design/tokens.css	Composants possédés (copiés dans le repo), accessibles (Radix), thémables par tokens — le contraire du « DaisyUI brut » de la v1. Introduit en R0 (primitives) et enrichi par release
Mobile	Expo (Expo Go) — R4	Démo par QR sans build natif ; leçons v1 consignées
IA	FastAPI (Python 3.13, uv) — R5	Écosystème IA Python ; n'écrit jamais en base métier
Déploiement	Docker + Dokploy (PaaS auto-hébergé)	Choix du référent ; portable (tout est compose)

Conséquences

• Un seul langage principal (TypeScript) du mobile à l'API — onboarding étudiant simplifié.
• La v1 sert de référence de lecture (décisions validées : machine à états OT, matrice de permissions en base, stock dérivé des mouvements, synchro à verrou optimiste) ; tout code V2 est réécrit et re-testé.
• Versions épinglées ; toute montée de version = tâche dédiée (risque n°5 du registre).