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 |