Files
CoHaiSe/docs/architecture.md
T
Gitea Actions 723b68ea80
deploy / deploy (push) Successful in 1m24s
feat: migrate showcase to Next.js and overhaul CRM UI
rebuild the public site on the Next.js App Router with static export,

per-section SEO pages, metadata, sitemap, robots and a generated OG image

add full-screen scroll-snap regions, staged scroll reveals, a hash-free

tab navigation with a sliding indicator and region-by-region menu scrolling

replace the theme text toggle with animated sun/moon icons

restructure the CRM API into config, middleware, models, routes, services

and utils layers

redesign the CRM shell with a single surface, tab rail, full-width blurred

DataTable, record dialogs and mask-based icons

update Docker/Nginx publishing, Makefile targets, shared UI polish and docs

Co-authored-by: Gitea Actions <-[email protected]>
2026-11-16 00:08:17 +00:00

174 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Architecture — CoHaiSe
Monorepo à deux applications déployées séparément :
| Application | Sous-domaine | Stack | Compose |
| --- | --- | --- | --- |
| Vitrine | `cohaise.dev` | Next.js 16 (export statique) + nginx | `docker-compose.yml` |
| CRM | `crm.cohaise.dev` | Next/Vite + API Node + MariaDB | `docker-compose.crm.yml` |
## Pile
| Élément | Version | Où |
| --- | --- | --- |
| React | 19 | `frontend/*` |
| Next.js (app router) | 16 | `frontend/web` |
| Vite | 8 | `frontend/crm` |
| Tailwind CSS | 4 (`@tailwindcss/postcss`) | `frontend/web/app/globals.css` |
| TypeScript | 7 | `tsconfig.json` (project references) |
| Hono + mysql2 + Zod | — | `backend/shared`, `backend/crm` |
`package.json` racine : `workspaces: ["frontend/*", "backend/*"]`, scripts
`build` (`tsc --build` puis build de chaque paquet), `typecheck`, `clean`.
`@cohaise/ui` doit être construit avant la vitrine : `tsc --build` s'en charge.
## Découpage
```
frontend/
shared/ @cohaise/ui — design system, dupliqué dans les 3 dépôts CoHaiSe
web/ @cohaise/web — la vitrine Next.js
crm/ @cohaise/crm-web — le front du CRM (React + Vite)
backend/
shared/ @cohaise/server — config, base, auth, http, migrations
crm/ @cohaise/crm — l'API du CRM
docker/ Dockerfile, Dockerfile.app, Dockerfile.api, nginx/, publish.sh
```
### Backend CRM
```
backend/crm/src/
index.ts composition du service (routes + purge des sessions)
admin.ts création/réinitialisation de comptes hors HTTP
config/app.ts constantes métier (pagination, rate-limit, source lead)
middleware/auth.ts montage de `attachUser` sur une ressource
models/types.ts lignes SQL et formes exposées par l'API
routes/*Routes.ts routes minces : validation Zod, HTTP, statuts
services/*Service.ts requêtes et règles métier
utils/ dbErrors, normalize, pagination, rateLimit, sql, validation
```
Le socle (`Db`, `App`, sessions, erreurs) reste dans `@cohaise/server` : la
réorganisation n'a changé ni la stack ni les contrats HTTP.
## Chaîne de build de la vitrine
Deux images, deux rôles :
1. **`docker/Dockerfile.app`** (`target: export`) — stage `builder` `node:22-slim` :
`npm ci`, puis `npm run build --workspace=frontend/shared` et
`--workspace=${APP_DIR}`. `OUTPUT_DIR` choisit le dossier produit (`out` pour
Next, `dist` pour Vite). Le stage `export` recopie ce dossier dans
`/app/dist`.
2. **`docker/publish.sh`** — tourne dans `app-build` avec le volume `app_data`
monté : copie dans `releases/<UTC>-<pid>`, puis bascule atomique du lien
`current` (`ln -sfn` + `mv -T`). La version précédente reste servie pendant
la copie ; une release plus vieille que 5 minutes est purgée.
Publication **atomique** : nginx ne voit jamais un répertoire à moitié écrit.
## Service de rendu
`docker/Dockerfile` : `nginx:1.27-alpine` + `docker/nginx/web.conf`.
| Point | Comportement |
| --- | --- |
| Racine | `/usr/share/nginx/html/current` (symlink) |
| `/healthz` | `200 ok`, log coupé |
| `/_next/static/` | `expires 1y`, `Cache-Control: public, immutable` |
| `/opengraph-image` | fichier sans extension servi en `image/png` |
| `/404.html` | page d'erreur générée par l'export Next |
| Racine applicative | `no-cache`, `try_files $uri $uri/ =404` (pas de fallback SPA) |
| gzip | actif, `min_length 1024` |
| En-têtes | `snippets/security-headers.conf` au niveau serveur **et** dans chaque `location` |
Chaque route Next est un dossier avec son `index.html` (`trailingSlash: true`).
## Front
- **App router** : `app/layout.tsx` porte le shell, les providers, le fond et les
métadonnées par défaut. Une page SEO autonome par section (`/services`,
`/demos`, `/stack`, `/about`, `/contact`), plus `/` qui compose les mêmes
sections. Le menu se comporte comme une barre d'onglets : une pastille
glisse d'une entrée à l'autre et l'URL ne reçoit **aucun `#`**. Sur
l'accueil, le clic fait défiler jusqu'à la région et l'onglet actif suit le
défilement ; depuis une page autonome, la cible est mémorisée dans
`sessionStorage` puis rejointe après le retour à `/`. Ces pages tiennent en
un écran (voir `globals.css`, règle `:only-child`) et ne défilent pas.
- **SEO** : `metadata` par page, canonical, OpenGraph/Twitter, JSON-LD
`Organization`/`WebSite`/`ProfessionalService` sur l'accueil, `sitemap.ts`,
`robots.ts` et `opengraph-image.tsx` généré (1200×630).
- **Bilingue** : toggle client FR/EN (`LanguageContext`). Le HTML prérendu est en
français — c'est la version indexée. La préférence stockée est appliquée après
le montage pour éviter tout mismatch d'hydratation.
- **Thème clair/sombre** : script inline dans `app/layout.tsx` (anti-FOUC) lit
`localStorage["cohaise-theme"]`, sinon `prefers-color-scheme`, puis pose la
classe `.dark` sur `<html>`. `ThemeContext` lit cet état après le montage.
Le bouton d'en-tête (`ThemeToggle`) est une icône seule : lune en clair,
soleil en sombre, avec étoile et transition rotation/fondu (`.theme-icon-*`
dans `globals.css`).
- **Régions plein écran** : chaque section est un `<section data-region>`
(`Section`) en `min-h-dvh` ; Stack et About partagent une seule région sur
l'accueil (`StackAbout`). `scroll-snap-type: y mandatory` +
`scroll-snap-stop: always` (voir `globals.css`) empêchent de s'arrêter entre
deux régions ou d'en sauter une. Le footer, hors région, s'aligne sur la fin
du viewport pour rester atteignable. Si une région dépasse la hauteur de
l'écran (téléphone étroit, texte long), `useScrollReveal` pose
`html[data-snap="off"]` et le snap est coupé pour ne pas bloquer le contenu.
Snap aussi désactivé en `prefers-reduced-motion` et sous 620 px de hauteur.
- **Animations** : `useScrollReveal` observe chaque `[data-region]` via une
bande centrale du viewport. Une fois la région stable à l'écran, ses
éléments `[data-reveal]` apparaissent en cascade après 0,25 s (le hero est
réglé à 0,05 s). Quitter la région avant la fin annule le minuteur : elle se
révélera au prochain passage. `data-reveal-delay` décale les voisins et
`prefers-reduced-motion` désactive tout. Pendant une séquence de menu
(`data-scroll-anim`), la région traversée est révélée sans délai.
- **Défilement** : GSAP `ScrollToPlugin` (`scrollToSection`) anime les sauts du
menu **région par région** (une étape par région traversée, courte
respiration entre chaque) ; le snap est suspendu le temps de la séquence
(`html[data-scroll-anim]`) pour que le navigateur ne saute pas directement à
la destination, et un geste de défilement l'interrompt. Pas de
`scroll-behavior: smooth` global, qui entrerait en conflit avec GSAP. Le snap
s'applique aux sections de `main[data-scroll-snap]`.
- **Fond WebGL** : `Topography` est un Client Component chargé via
`next/dynamic` avec `ssr: false`, en position fixed derrière le contenu.
- **Contact** : le formulaire POSTe vers `POST /api/crm/leads` du CRM
(`NEXT_PUBLIC_CRM_API_URL` au build, sinon `https://crm.cohaise.dev`).
## Front CRM
- **Shell fixe** : `Crm` occupe `h-dvh` en `overflow-hidden` ; l'en-tête reste
figé et le reste du viewport est **une seule surface** : rail d'onglets à
gauche (15 % à partir de `md`, icônes seules en dessous), vue des données à
droite. La page ne défile jamais ; seules les zones de contenu portent leur
propre défilement (`DataTable`, formulaire du dialogue).
- **Profondeur** : seul l'en-tête porte `.glass` (flou d'arrière-plan). La
surface de travail est un simple voile `bg-surface/40` sans flou ; c'est le
`DataTable` qui porte son propre fond translucide et flouté.
- **DataTable** : `components/DataTable.tsx` affiche la liste triable, la
recherche, les actions de ligne, le squelette, l'état vide et les cartes
mobiles. L'en-tête reste collé et le tableau défile dans son cadre
(`overflow-auto`). Les pages ne réimplémentent plus de `<table>`.
- **Saisie** : `RecordDialog` borne le formulaire à la hauteur de l'écran ;
seul le corps du dialogue défile, y compris sur téléphone.
- **Fond** : `FaultyTerminalBackdrop` est monté sur l'écran connecté, la
connexion, le changement de mot de passe et l'attente de session.
## Jetons
`frontend/shared/src/styles/tokens.css` est la source des couleurs ; Tailwind 4
les reçoit par `@theme inline` (`theme.css`). La vitrine importe le design system
depuis `app/globals.css` :
```css
@import "tailwindcss";
@import "@cohaise/ui/styles";
@source "../../shared/src";
```
`--cohaise-destructive` est un rouge (`#d32f2f` clair / `#ef4444` sombre),
l'accent de marque est le carmin `--cohaise-accent` (`#b71c1c`), l'avertissement
reste jaune (`--cohaise-warning`). Voir `standards.md`.