docs(r0): architecture — ADR-001 stack, ADR-002 démo-login, C4, modèle R0

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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

@@ -0,0 +1,31 @@
+# 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).

docs/03-architecture/adr/ADR-002-demo-login.md

@@ -0,0 +1,34 @@
+# ADR-002 — Sélecteur de compte de démonstration (`DEMO_MODE`)
+
+- **Statut** : acceptée (R0, 15 juillet 2026)
+- **Contexte** : demande explicite du référent après la v1 — tester avec plusieurs rôles
+  obligeait à se déconnecter/reconnecter sans cesse, en local comme sur l'instance en ligne.
+  C'est aussi un besoin de **démonstration commerciale** (montrer chaque persona en 1 clic).
+
+## Décision
+
+1. Une variable d'environnement **`DEMO_MODE`** (`true`/absent) contrôle le mode démo,
+   côté API **et** côté web (`VITE_DEMO_MODE` injectée au build ou servie par `/auth/demo-accounts`).
+2. Quand `DEMO_MODE=true` :
+   - `GET /auth/demo-accounts` (**publique**) liste les comptes de démonstration seedés
+     (id, nom, rôle, initiales — jamais de secret) ;
+   - `POST /auth/demo-login { userId }` (**publique**) émet un JWT pour ce compte **sans
+     mot de passe** — uniquement pour les comptes marqués `isDemo=true` en base ;
+   - le web affiche la liste sur l'écran de connexion **et** un sélecteur dans la topbar
+     (bascule instantanée, marquage visuel « DÉMO » safran permanent).
+3. Quand `DEMO_MODE` est absent/faux : **les deux routes n'existent pas** (404 — le module
+   n'est pas enregistré), le web n'affiche rien. Test e2e dédié qui vérifie le 404.
+
+## Sécurité
+
+- Le danger réel est un `DEMO_MODE=true` oublié en production. Parades : (a) le module
+  refuse de démarrer si `DEMO_MODE=true` **et** `NODE_ENV=production` sauf si
+  `DEMO_MODE_I_KNOW=true` (double verrou explicite pour l'instance de démo publique) ;
+  (b) `isDemo` en base — un compte réel ne peut jamais être emprunté ; (c) bannière
+  « DÉMO » permanente dans l'UI.
+- Critère d'acceptation (exigences) : passer d'Administrateur à Technicien en **< 3 s**.
+
+## Conséquences
+
+Le seed crée 7 comptes `isDemo` (un par rôle). Les environnements : dev local
+(`DEMO_MODE=true`), démo en ligne (`true` + double verrou), production client (absent).