Files
CoHaiSe/docs/architecture.md
T
Esiah 09cf07d79b 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
2026-11-16 00:52:29 +01:00

8.7 KiB
Raw Blame History

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 :

@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.