# 2. Architecture et flux

## Topologie logique

| Composant | Reçoit | Produit | Dépendances |
|---|---|---|---|
| Navigateur | HTML/JS du frontend | Requêtes `/api/*` | Caddy en production |
| Frontend | Actions utilisateur | Appels API authentifiés | Backend |
| Backend | HTTP, cookie JWT ou Bearer | JSON, DOCX, PDF | MySQL, volumes, Microsoft Entra/Graph |
| MySQL | Requêtes Prisma | Données structurées | Volume `db_data` |
| Scheduler | Horloge Europe/Paris | Déclenchement de campagnes | Backend/Graph/MySQL |
| Stockage modèles | DOCX importés | Sources de génération | Volume `document_templates_data` |
| Stockage paies | PDF mensuels | Bulletin PDF extrait | Bind mount `${PAYSLIP_HOST_PATH}` |
| Caddy | HTTPS public/interne | Proxy frontend/backend | DNS et certificats |

En production, Caddy route `https://rhconnect.envie2enord.com/api/*` vers `backend:8000` et le reste vers `frontend:3000`.

## Flux d’une requête métier

1. L’utilisateur s’authentifie localement ou via Microsoft Entra ID.
2. Le backend émet un JWT et le place dans le cookie `auth_token`.
3. Le frontend appelle une route `/api/...`.
4. La route vérifie l’identité, la permission de module et le niveau `read` ou `write`.
5. Les scopes salarié sont construits : secteurs, établissements, catégories et types de contrat.
6. La route valide le corps avec Zod puis délègue au service métier.
7. Le service interroge Prisma et retourne une donnée filtrée.
8. La route sérialise la réponse ou un fichier.

## Séparation des responsabilités

Une évolution saine suit cette répartition :

- page/composant frontend : saisie, affichage et expérience utilisateur ;
- route API : protocole HTTP, auth, validation, codes de réponse ;
- validator Zod : forme et contraintes de l’entrée ;
- service : règle métier et transaction ;
- Prisma : persistance et relations ;
- tests : cas normal, limites, droits et régression.

Éviter d’implémenter une règle RH uniquement dans un composant. Elle serait contournable par un appel direct à l’API et dupliquée dans les exports.

## Données et fichiers

MySQL ne contient pas tous les octets utiles à l’application.

| Contenu | Stockage | Sauvegarde requise |
|---|---|---|
| Salariés, contrats, droits, métadonnées | MySQL `app_db` | Dump SQL cohérent |
| Modèles DOCX importés | `/data/document-templates` dans le backend | Archive du volume en conservant l’arborescence |
| Bulletins mensuels | `/data/paies` dans le backend | Sauvegarde de la source hôte/partage réseau |
| Code et migrations | Git | Dépôt distant et tags/releases |
| Secrets | `.env.production` sur le serveur | Coffre-fort ou procédure DSI, jamais Git |

Une restauration de MySQL sans les modèles DOCX rend les lignes `versions_modeles_documents` présentes mais leurs fichiers introuvables. L’inverse laisse des fichiers impossibles à sélectionner depuis l’application.

## API et documentation

Le backend possède environ 94 chemins OpenAPI et 159 opérations dans la version analysée. Les endpoints de consultation et modification couvrent les domaines principaux, ainsi que `/health`, `/openapi` et l’interface `/api-docs` si Swagger est activé.

Après ajout ou modification de routes documentées :

```bash
cd backend/backend_envie2e
node scripts/generate-openapi-routes.mjs
```

Vérifier ensuite que la spécification et l’interface Swagger correspondent réellement aux validations Zod et aux permissions appliquées.