Files
CoHaiSe-CLOUD/docs/architecture.md
T
Esiah 68d4d5dea0
PR — Ouverture automatique / create-pr (push) Successful in 3s
refactor: restructure frontend and backend by domain services
Split the monolithic backend (lib/, routes/, access.ts, storage.ts, media.ts)
into a layered structure inspired by JeanXXIII-CRM:
- config/: appConfig, db
- middleware/: auth (session, roles, cookies)
- models/: shared types
- routes/: *Routes.ts (thin HTTP handlers)
- services/: *Service.ts (business logic, one per domain)
- utils/: errors, http, migrate, ratelimit, validators, service bootstrap

Frontend likewise: services/*Service.ts + apiClient, contexts/, types/, utils/format.
Route files now carry the "Routes" suffix; service files are named
authService.ts, ratelimit.ts, etc. and live in their own files, frontend and
backend separated.

Updated docs and READMEs to reflect the new layout. Typecheck and builds pass.
2026-11-13 09:45:21 +01:00

4.9 KiB

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.
  • 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}/<slug>/<uuid><ext> (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 <input type=file> : 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/.