Files
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

110 lines
4.9 KiB
Markdown

# 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}/<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/`.