# Choix technologiques — Der-topogo

Site de consulting IAM et sécurité informatique, avec contenu éditable via un CMS headless intégré à l’application.

## Architecture générale

- **Application full-stack** : [Next.js](https://nextjs.org/) (App Router) en TypeScript, avec sortie **standalone** pour des images Docker légères et un déploiement prévisible.
- **CMS** : [Payload CMS](https://payloadcms.com/) v3, embarqué dans Next via `@payloadcms/next` (routes admin et API sous le même processus Node).
- **Base de données** : [PostgreSQL](https://www.postgresql.org/) via l’adaptateur officiel `@payloadcms/db-postgres` (chaîne `DATABASE_URI` / variable d’environnement). La base n’est pas fournie par le `docker-compose` du dépôt : elle est attendue en externe ou sur un autre compose.
- **Médias** : volume Docker `app_media` monté sur `/app/media` pour la persistance des fichiers uploadés depuis Payload.
- **Reverse proxy / TLS** : [Caddy](https://caddyserver.com/) en production (TLS automatique Let’s Encrypt sur le domaine public, TLS interne pour l’accès LAN). Compression gzip/zstd, en-têtes de sécurité alignés avec ceux définis dans Next.

## Choix détaillés

| Domaine | Choix | Raison |
|--------|--------|--------|
| Framework UI | Next.js + React | SSR/SSG, intégration native avec Payload, écosystème mature. |
| Langage | TypeScript (strict) | Typage des collections Payload et du front, maintenance à long terme. |
| Styles | Tailwind CSS v4 + PostCSS | Utilitaires, cohérence visuelle, build via `@tailwindcss/postcss`. |
| Éditeur riche | Lexical (`@payloadcms/richtext-lexical`) | Éditeur moderne supporté officiellement par Payload 3. |
| Animations | Framer Motion | Animations déclaratives côté client sans réécrire la logique de layout. |
| Icônes | Lucide React | Jeu d’icônes léger et cohérent avec React. |
| Classes CSS conditionnelles | `clsx` + `tailwind-merge` | Composition de classes et fusion sans conflits avec Tailwind. |
| Images | `sharp` | Requis / recommandé par Next pour l’optimisation d’images en production. |
| API Payload / introspection | `graphql` | Dépendance utilisée par l’écosystème Payload pour GraphQL. |
| Déploiement app | Docker multi-stage (Node 20 Alpine) | `npm ci`, build Next, image finale non-root (`nextjs`) exposant le port 3000. |
| Télémétrie | `NEXT_TELEMETRY_DISABLED=1` | Désactivée dans l’image Docker. |

## Sécurité HTTP (résumé)

- En-têtes côté Next : `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy` (voir `next.config.ts`).
- Caddy renforce HSTS sur le site public et reprend des en-têtes similaires sur les deux blocs de site.

---

# Paquets et logiciels installés / référencés

Les **versions exactes** des paquets npm transitifs sont dans `package-lock.json` à la racine du dépôt. Après `npm install`, la commande `npm ls` liste l’arbre complet.

## Dépendances de production (`dependencies` dans `package.json`)

| Paquet | Rôle |
|--------|------|
| `payload` | Moteur CMS (collections, auth, API REST/GraphQL). |
| `@payloadcms/next` | Intégration Next.js (handler, build). |
| `@payloadcms/db-postgres` | Persistance PostgreSQL (Drizzle sous le capot côté Payload). |
| `@payloadcms/richtext-lexical` | Champ rich text Lexical dans l’admin. |
| `graphql` | Support GraphQL attendu par Payload. |
| `sharp` | Traitement d’images pour `next/image`. |
| `framer-motion` | Animations React. |
| `lucide-react` | Icônes SVG. |
| `clsx` | Concaténation conditionnelle de noms de classes. |
| `tailwind-merge` | Fusion des classes Tailwind sans doublons contradictoires. |

## Dépendances de développement (`devDependencies`)

| Paquet | Rôle |
|--------|------|
| `next` | Framework (installé comme dépendance transitive via l’écosystème Next / ESLint ; version figée dans le lockfile). |
| `react` / `react-dom` | Installés avec Next (versions dans le lockfile). |
| `typescript` | Typage (souvent amené par Next selon le template). |
| `tailwindcss` | Moteur Tailwind v4. |
| `@tailwindcss/postcss` | Plugin PostCSS pour Tailwind 4. |
| `postcss` | Pipeline CSS. |
| `eslint` | Lint JavaScript/TypeScript. |
| `eslint-config-next` | Règles ESLint alignées sur la version de Next utilisée. |

> **Note** : Le fichier `package.json` ne liste pas explicitement `next` ni `react` : ils sont tirés par les outils (p. ex. `eslint-config-next`) et le scaffold Next ; les versions réellement installées sont celles du **lockfile**.

## Infrastructure (hors `node_modules`)

| Composant | Détail |
|-----------|--------|
| **Node.js** | Ligne de base des images : **20** (variante **Alpine** dans le `Dockerfile`). |
| **npm** | Utilisé pour `npm ci` et les scripts (`build`, `start`, etc.). |
| **Docker** | Build multi-étapes : `deps` → `builder` → `runner`. |
| **PostgreSQL** | Attendu via `DATABASE_URI` ; non défini dans le compose minimal du repo. |
| **Caddy** | Fichier `Caddyfile` à la racine : reverse proxy vers `app:3000`, logs, TLS. |

## Fichiers de configuration utiles

- `package.json` / `package-lock.json` — dépendances npm.
- `next.config.ts` — Next + `withPayload`, standalone, en-têtes, alias Webpack.
- `tsconfig.json` — chemins `@/*` et `@payload-config`.
- `postcss.config.mjs` — Tailwind via PostCSS.
- `src/payload.config.ts` — collections, Lexical, Postgres.
- `Dockerfile` — image de production.
- `docker-compose.yml` — service `app`, volume médias, `env_file: .env.local`.
- `Caddyfile` — exposition HTTPS et proxy.

## Flux Git de déploiement (mémo)

Ce flux est déjà décrit en détail dans `DEPLOY.md`. Rappel opérationnel rapide :

### 1) Depuis le poste de dev (push vers Chillka)

```bash
git add .
git commit -m "message"
git push origin main
```

### 2) Sur Huitral (pull + redéploiement)

```bash
ssh toshiro@huitral
cd /var/www/der-topogo
git pull origin main
docker compose up -d --build
```

### 3) Vérification rapide

```bash
docker compose ps
curl -Ik https://dt.arauco.online
curl -Ik https://dt.huitral.ruka.lan
```

Si le certificat local est auto-signé, utiliser `curl -Ik` (avec `-k`) sur le domaine LAN.

---

*Document généré pour décrire l’état du dépôt ; mettre à jour ce fichier lors d’ajouts ou de montées de version majeures des dépendances.*