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

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-08 12:41:54 +00:00 · 2026-07-15 21:26:27 +01:00
parent 04e61056f6
commit ddc9dc52b5
4 changed files with 205 additions and 0 deletions
--- a/docs/03-architecture/architecture.md
+++ b/docs/03-architecture/architecture.md
@@ -0,0 +1,71 @@
+# Architecture — SIOP V2
+
+> **Rôle de ce document (playbook)** : la vue d'ensemble en 3 niveaux (méthode C4
+> simplifiée : contexte → conteneurs → composants). Les décisions structurantes sont
+> tracées en ADR (`adr/`). Mis à jour à chaque release.
+
+## Niveau 1 — Contexte
+
+```
+  Gardien (Karim) ──scan QR──▶ ┌─────────────────┐ ◀──navigateur── Bureau (Salma, Nadia, direction)
+                               │                 │
+  Technicien (Ahmed) ─mobile─▶ │    SIOP V2      │ ──emails──▶ demandeurs / alertes stock
+                               │                 │
+  Notices, historiques ──────▶ └─────────────────┘
+        (ingestion RAG, R5)
+```
+
+## Niveau 2 — Conteneurs
+
+```
+┌───────────────────────────── Dokploy (Docker) ─────────────────────────────┐
+│                                                                            │
+│  apps/web ── nginx ──/api──▶ apps/api (NestJS) ──▶ PostgreSQL 18           │
+│  (React 19, statique)        │  auth JWT, permissions, métier              │  (+ pgvector, PostGIS)
+│                              │──▶ Redis (BullMQ : jobs préventif, R2)      │
+│  apps/mobile (Expo, R4) ────▶│──▶ MinIO (FileStorage : photos, documents)  │
+│        /sync                 │                                             │
+│  apps/ai (FastAPI, R5) ◀─────┘ (lecture métier via API ; écrit seulement   │
+│        RAG, embeddings          les embeddings pgvector)                   │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+Règles de dépendance : **toutes les écritures métier passent par l'API NestJS** ; le web et
+le mobile ne parlent qu'au contrat OpenAPI ; MinIO n'est accédé qu'à travers `FileStorage`.
+
+## Niveau 3 — Composants de l'API (état R0)
+
+```
+apps/api/src
+├── auth/          JWT (access), guard global « fermé par défaut », @Public(),
+│                  démo-login (module conditionnel DEMO_MODE — ADR-002)
+├── permissions/   matrice rôles × objets × droits (en base, cache 60 s),
+│                  @RequirePermission(objet, droit) + PermissionsGuard
+├── users/         profils (R0 : lecture du profil courant ; gestion complète R1)
+├── health/        /health (base, Redis, MinIO) — public
+├── prisma/        PrismaService (client généré)
+└── common/        zodToOpenApi, ZodValidationPipe, filtres d'erreurs
+```
+
+Chaque release ajoute ses modules (R1 : locations/assets/categories/teams ; R2 :
+work-orders/requests/preventive ; …) — le document est enrichi à chaque clôture.
+
+## La « règle d'or » du contrat
+
+```
+packages/shared (Zod) ──zodToOpenApi──▶ docs/openapi.json (committée)
+                                            │ openapi-typescript
+                                            ▼
+                             clients typés web / mobile (générés)
+```
+
+Toute modification d'API régénère spec + clients **dans le même commit** ; la CI
+(`ci-contract`) échoue sur le moindre diff. Le front ne peut structurellement pas dériver.
+
+## Environnements
+
+| Env | `DEMO_MODE` | Données | Où |
+| --- | --- | --- | --- |
+| dev local | `true` | seed démo | Docker local (`pnpm infra:up`) |
+| démo en ligne | `true` (+ double verrou) | seed démo | Dokploy |
+| production client | absent | réelles | Dokploy |