# Architecture — CoHaiSe Cloud Fichiers et médias : arborescence de dossiers, envoi, téléchargement, corbeille, recherche, galerie, partage nominatif, comptes et administration. Une API Node/TypeScript, une base MariaDB, un stockage de fichiers monté en volume. ## Pile | Élément | Où | | --- | --- | | React 19 + Vite 8 + Tailwind 4 + react-router-dom 7 | `frontend` | | Hono | `backend/src/index.ts` (`src/utils` pour le socle HTTP) | | MariaDB (`mysql2`) | `backend/src/config/db.ts` | | Nodemailer | `backend/src/services/mailService.ts` | | sharp (vignettes) | `backend/src/services/mediaService.ts` | | Validation Zod | `backend/src/config/appConfig.ts`, `src/utils/validators.ts` et chaque route | ## Découpage ``` backend/src/config/ configuration et connexion base (appConfig, db) backend/src/middleware/ gardes HTTP (auth : session, rôles) backend/src/models/ types partages (types.ts) backend/src/routes/ routeurs HTTP fins, un par domaine (*Routes.ts) backend/src/services/ logique metier, un fichier par domaine (*Service.ts) backend/src/utils/ socle technique : errors, http, ratelimit, validators, migrate, service backend/src/ index.ts (bootstrap), cli.ts, admin.ts backend/migrations/ 000 … 010 frontend/src/services/ clients API par domaine (*Service.ts + apiClient.ts) frontend/src/contexts/ SessionContext, ThemeContext, I18nContext frontend/src/types/ types partages du front frontend/src/utils/ formatage (format.ts) frontend/src/ui/ design system (boutons, cartes, champs, spinner) frontend/src/ router + AppShell + pages/ docker/ Dockerfile(.app/.api), nginx/, publish.sh ``` `backend/src/utils` porte la mécanique générique (erreurs, HTTP, migrations, limitation de débit, validation), `backend/src/services` porte le métier : sessions, droits, quotas, chemins disque, traitement média, courriel. Tout vit dans un seul paquet, sans dépendance de workspace. ## Chaîne de démarrage `docker-compose.yml` — projet **`cohaise-cloud`**, 5 services : ``` db ──healthy──▶ migrate (runMigrations + assertNoDrift, puis s'arrête) │ └──service_completed_successfully──▶ api ──▶ nginx app-build (publish.sh, terminé avant nginx) ``` - `migrate` monte `./backend/migrations:/migrations:ro`. - `api` refuse de démarrer si une migration appliquée a été modifiée (dérive de checksum). `onReady` purge les sessions, la corbeille et les envois inachevés, puis un balayage horaire reprend ces purges sans redémarrage. - stockage : `app_data` (volume Docker, HTML), `$CLOUD_DB_DIR` (MariaDB) et `$CLOUD_MEDIA_DIR` (fichiers) en bind mounts hôte. ## API et front - API `/api/cloud` : voir [`api.md`](api.md). - Front : React Router (`frontend/src/App.tsx`) avec gardes `RequireAuth` / `RequireReady` / `RequireAdmin` et `AppShell` (`components/AppShell.tsx`) : navigation latérale, en-tête, contenu. - Pages : `Login`, `ForgotPassword`, `ResetPassword`, `ConfirmEmail`, `ChangePassword`, `Browser`, `Search`, `Gallery`, `Trash`, `Profile`, `Admin` (comptes / stockage / journal). - Client HTTP unique `services/apiClient.ts` (base `/api/cloud`, `same-origin`) ; services par domaine dans `services/*Service.ts` ; contexte de session `contexts/SessionContext.tsx` ; dialogues réutilisables dans `components/dialogs.tsx`. - En-têtes nginx : CSP stricte, HSTS, `nosniff`, `Referrer-Policy`, `Permissions-Policy` (`docker/nginx/snippets/`). `X-Frame-Options` est remplacé par `frame-ancestors 'none'` dans la CSP. - Dev : Vite **5174**, proxy `/api` → `http://127.0.0.1:3101`. Prod : nginx sert le SPA avec repli `try_files … @spa` (liens profonds pris en charge). ## Sessions - Cookie `cohaise_session` : `httpOnly`, `SameSite=Lax`, `path=/`, `secure` déduit du schéma réel (et de `TRUST_PROXY`). - En base, uniquement le **SHA-256** du jeton. TTL `SESSION_TTL_HOURS`. - Changement de mot de passe ⇒ révocation des autres sessions ; gestion fine depuis la page compte. ## Stockage et médias - `MEDIA_DIR=/data/media/originals`, `VARIANT_DIR=/data/media/variants`. - Chemin physique `${MEDIA_DIR}//` (`storageService.ts`), nom affiché jamais dans le chemin. - `mediaService.ts` : classification (`image/video/audio/document/archive/other`), vignette (`sharp`, seuil 480 px) écrite dans `VARIANT_DIR`, métadonnées dans `media_metadata` / `file_variants`. Indexation **best-effort** après upload. - Avatars dans `user_avatars`. ## Corbeille Suppression douce (`deleted_at`). `purgeExpiredTrash` (démarrage + accès) purge au-delà de `trash_retention_days`. Restauration et purge manuelles exposées via `/trash`. ## Limites connues - Upload séquentiel par `` : pas de drag & drop, pas de reprise de transfert, pas de multipart. - `docker/README.md` (et tout README de paquet) peut décrire un état antérieur : se fier à `docs/`.