siop2/docs/03-architecture/architecture.md

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