refactor: restructure frontend and backend by domain services
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.
This commit is contained in:
2026-11-13 09:45:21 +01:00
parent d837817bcb
commit 68d4d5dea0
103 changed files with 5415 additions and 4711 deletions
+11 -7
View File
@@ -32,8 +32,8 @@ CI). L'exécuter avant de déclarer un travail fini.
seulement. Le checksum bloquerait le démarrage.
5. **API admin** : les routes `/api/cloud/admin/*` existent (UI Administration).
La CLI (`make admin`) reste pour l'amorçage et les cas hors ligne.
6. **Chemin disque** : toujours via `storage.ts` (`resolveInside`), jamais par
concaténation depuis une entrée utilisateur.
6. **Chemin disque** : toujours via `services/storageService.ts` (`resolveInside`),
jamais par concaténation depuis une entrée utilisateur.
7. **404 plutôt que 403** sur une ressource non accessible : ne pas introduire
d'énumération.
8. **CSP stricte** : pas de script en ligne dans `index.html` (utiliser un
@@ -42,13 +42,17 @@ CI). L'exécuter avant de déclarer un travail fini.
## Conventions
- TypeScript strict, project references racine.
- Back : `routes/*Routes.ts` (HTTP fin) appellent `services/*Service.ts`
(métier) ; le socle vit dans `config/`, `middleware/`, `utils/`, les types
partagés dans `models/types.ts`.
- Hono + Zod : toute route avec corps passe par un schéma Zod dédié.
- Erreurs : `AppError` + codes (`errors.ts`) — jamais `throw` brut, jamais de
détail de schéma dans une 500.
- Erreurs : `AppError` + codes (`utils/errors.ts`) — jamais `throw` brut, jamais
de détail de schéma dans une 500.
- SQL : requêtes préparées uniquement, pas de `raw()` hors DDL.
- Front : un seul client HTTP (`frontend/src/lib/api.ts`),
`credentials: "same-origin"`. React Router 7 (`App.tsx`) + `AppShell`, contexte
de session dans `lib/session.tsx`.
- Front : un client HTTP (`frontend/src/services/apiClient.ts`), puis un service
par domaine (`services/*Service.ts`), `credentials: "same-origin"`. React
Router 7 (`App.tsx`) + `AppShell`, contexte de session dans
`contexts/SessionContext.tsx`.
- `.editorconfig` : 2 espaces, LF, UTF-8.
## Design system
+6 -6
View File
@@ -91,7 +91,7 @@ l'offset exact.
### Discussion (chat d'un dossier et membres)
Chaque dossier possède son propre salon. Le droit d'accès au dossier fait loi :
lecture comme écriture passent par `canRead` (`backend/src/access.ts`), donc le
lecture comme écriture passent par `canRead` (`backend/src/services/auditService.ts`), donc le
salon d'un dossier `public` est ouvert à tout compte authentifié. La lecture est
en texte brut, React échappe le rendu. La synchronisation est incrémentale par
identifiant (`after`), sans WebSocket.
@@ -158,7 +158,7 @@ utilise alors le sien.
## Droits d'accès
Calculés **en base à chaque requête**, depuis la session — jamais depuis un
en-tête (`backend/src/access.ts`).
en-tête (`backend/src/services/auditService.ts`).
| Concept | Règle |
| --- | --- |
@@ -190,9 +190,9 @@ par tous les membres authentifiés, en écriture pour son propriétaire.
## Courriels
Les messages sortants sont construits par `backend/src/lib/mail-template.ts` :
gabarit HTML aux couleurs de l'app (`#b71c1c`), logo, bouton d'action et mention
**ne pas répondre**. Un repli texte accompagne chaque envoi.
Les messages sortants sont construits par `backend/src/services/mailService.ts`
(gabarit HTML aux couleurs de l'app (`#b71c1c`), logo, bouton d'action et mention
**ne pas répondre**). Un repli texte accompagne chaque envoi.
Le logo `backend/src/assets/logo.png` est **embarqué** dans le message (pièce
jointe `cid`), donc visible même quand le client bloque les images distantes.
@@ -229,7 +229,7 @@ audit_logs, user_file_stars, chat_reads`.
## Erreurs métier
`AppError` avec codes stables (`backend/src/lib/errors.ts`). Correspondances
`AppError` avec codes stables (`backend/src/utils/errors.ts`). Correspondances
MariaDB : `1062` → 409, `1146` → 503 `NOT_MIGRATED`, `1406` → 422. Le corps d'une
500 ne contient jamais de détail de schéma. Réponse normalisée :
+30 -20
View File
@@ -9,27 +9,36 @@ Node/TypeScript, une base MariaDB, un stockage de fichiers monté en volume.
| Élément | Où |
| --- | --- |
| React 19 + Vite 8 + Tailwind 4 + react-router-dom 7 | `frontend` |
| Hono | `backend/src/index.ts` (`src/lib` pour le socle) |
| MariaDB (`mysql2`) | `backend/src/lib/db.ts` |
| Nodemailer | `backend/src/lib/mail.ts` |
| sharp (vignettes) | `backend/src/media.ts` |
| Validation Zod | `backend/src/lib/config.ts` et chaque route |
| 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/lib/ socle serveur : config, db, mail, mail-template, ratelimit, http, service, auth, errors
backend/src/ routes/, access.ts, storage.ts, media.ts, admin.ts
backend/migrations/ 000 … 006
frontend/src/ui/ design system (boutons, cartes, champs, spinner)
frontend/src/ router + AppShell + pages/
docker/ Dockerfile(.app/.api), nginx/, publish.sh
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/lib` porte la mécanique générique (sessions, erreurs,
migrations, courriel, limitation de débit), le reste de `backend` porte le
métier : droits, quotas, chemins disque, traitement média. Tout vit dans un seul
paquet, sans dépendance de workspace.
`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
@@ -58,8 +67,9 @@ app-build (publish.sh, terminé avant nginx)
- Pages : `Login`, `ForgotPassword`, `ResetPassword`, `ConfirmEmail`,
`ChangePassword`, `Browser`, `Search`, `Gallery`, `Trash`, `Profile`,
`Admin` (comptes / stockage / journal).
- Client HTTP unique `lib/api.ts` (base `/api/cloud`, `same-origin`) ; contexte
de session `lib/session.tsx` ; dialogues réutilisables dans
- 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
@@ -78,9 +88,9 @@ app-build (publish.sh, terminé avant nginx)
## Stockage et médias
- `MEDIA_DIR=/data/media/originals`, `VARIANT_DIR=/data/media/variants`.
- Chemin physique `${MEDIA_DIR}/<slug>/<uuid><ext>` (`storage.ts`), nom affiché
jamais dans le chemin.
- `media.ts` : classification (`image/video/audio/document/archive/other`),
- 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`.
+1 -1
View File
@@ -12,7 +12,7 @@ Réponse sur **`http://localhost:8083`**.
La configuration est validée **avant** l'ouverture d'aucun port : si une variable
manque ou est mal formée, le process s'arrête en listant exactement ce qui
pose problème (`backend/src/lib/config.ts`).
pose problème (`backend/src/config/appConfig.ts`).
## Variables
+3 -3
View File
@@ -18,7 +18,7 @@
### Limitation de débit
- **Applicatif** : `createRateLimiter` (`backend/src/lib/ratelimit.ts`) par IP
- **Applicatif** : `createRateLimiter` (`backend/src/utils/ratelimit.ts`) par IP
sur `auth/login`, `account/forgot-password`, `account/reset-password`,
`account/email-change`. Réglages `RATE_LIMIT_LOGIN_MAX` (10) et
`RATE_LIMIT_LOGIN_WINDOW_MS` (60 s).
@@ -36,7 +36,7 @@
### Droits d'accès
Calculés **en base à chaque requête**, depuis la session — jamais depuis un
en-tête (`backend/src/access.ts`). Lecture : propriétaire, permission
en-tête (`backend/src/services/auditService.ts`). Lecture : propriétaire, permission
`folder_permissions` (`read`/`write`/`admin`), ou dossier `public`. Écriture :
`write`/`admin`. **404 plutôt que 403** : jamais d'indice sur l'existence d'une
ressource.
@@ -64,7 +64,7 @@ d'écriture par compte sur 10 s), édition et épinglage compris.
### Courriel
Nodemailer (`backend/src/lib/mail.ts`) avec `SMTP_HOST`. `PUBLIC_ORIGIN`
Nodemailer (`backend/src/services/mailService.ts`) avec `SMTP_HOST`. `PUBLIC_ORIGIN`
(obligatoire) construit les liens de réinitialisation et de confirmation ;
aucun HTML utilisateur n'est injecté dans les messages.
+1 -1
View File
@@ -54,7 +54,7 @@ Design system local à `frontend/src/ui` : `Button`, `Card`, `Input`,
| Élément | Attendu |
| --- | --- |
| Socle & design system | internes à `backend/src/lib` et `frontend/src/ui` |
| Socle & design system | internes à `backend/src/{config,middleware,utils}` et `frontend/src/ui` |
| Port HTTP | `8083` (`COHAISE_HTTP_PORT`) |
| Dépôt | autonome, importance égale front et back |
| `.env` | jamais versionné (`.env.example` seulement) |
+8 -8
View File
@@ -33,13 +33,13 @@ fichier est copié dans l'image, pas monté.
## Modifier une route
1. Schéma d'entrée : Zod dans `backend/src/routes/<entity>.ts`.
2. Droits : passer par `backend/src/access.ts` (jamais par un paramètre
venu du client).
1. Schéma d'entrée : Zod dans `backend/src/routes/<entity>Routes.ts`.
2. Droits : passer par `backend/src/services/auditService.ts` (jamais par un
paramètre venu du client).
3. Réponse : renvoyer **404** si la ressource n'est pas censée exister pour ce
compte, 403 seulement pour une règle explicite.
4. Erreur métier : `AppError` depuis `backend/src/lib/errors.ts`.
5. Audit si l'action est sensible (`audit()` dans `access.ts`).
4. Erreur métier : `AppError` depuis `backend/src/utils/errors.ts`.
5. Audit si l'action est sensible (`audit()` dans `services/auditService.ts`).
6. `make check`, puis redémarrage de l'API (`docker compose up -d api`).
## Modifier le schéma
@@ -65,10 +65,10 @@ Le design system vit dans `frontend/src/ui` (+ `src/styles`).
| Besoin | Fichier |
| --- | --- |
| Droit d'accès à un dossier/fichier | `backend/src/access.ts` |
| Droit d'accès à un dossier/fichier | `backend/src/services/auditService.ts` |
| Taille/quota par défaut | migration `004`, table `users` / `settings` |
| Chemin physique des fichiers | `backend/src/storage.ts` |
| En-têtes, CORS, healthz | `backend/src/lib/http.ts` |
| Chemin physique des fichiers | `backend/src/services/storageService.ts` |
| En-têtes, CORS, healthz | `backend/src/utils/http.ts` |
| Durée de session | `SESSION_TTL_HOURS` |
| Port | `COHAISE_HTTP_PORT` (nginx), `COHAISE_API_PORT` (API) |
| Interface (parcours dossiers) | `frontend/src/pages/Browser.tsx` |