PR — Ouverture automatique / create-pr (push) Successful in 3s
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.
110 lines
4.9 KiB
Markdown
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/`.
|