Files
CoHaiSe-CLOUD/docs/architecture.md
T
Gitea ActionsandEsiah f689ab4d57
CD — Deployment / deploy (push) Successful in 34s
refactor: restructure frontend and backend by domain services (#26)
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.

---------

Co-authored-by: xEsiah <[email protected]>
Reviewed-on: #26
Reviewed-by: Esiah <[email protected]>
Co-authored-by: Gitea Actions <-[email protected]>
2026-11-13 09:13:27 +00: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/.