From 22b7b8762fd4afcd8238eb9729dd76fa6f95a9f7 Mon Sep 17 00:00:00 2001
From: Nicolas FRYDER <n.fryder@equilibre-structures.fr>
Date: Thu, 20 Aug 2026 16:44:26 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20d=C3=A9crire=20les=20services=20et=20la?=
 =?UTF-8?q?=20porte=20de=20qualit=C3=A9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Le README était réduit à « test 4 ». Il documente désormais les sept services,
le fait que crawler et flaresolverr ne tournent qu'en dev, et surtout
l'installation du hook pre-push — seul filet entre `git push` et la mise en
ligne, le déploiement partant sur webhook.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index efa868a..b99d97e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,53 @@
 # Stack metalfrom.eu
-test 4
+
+Carte des groupes de metal européens, données issues de Metal Archives
+(avec accord du propriétaire du site source).
+
+## Services
+
+| Service            | Rôle                                                            |
+|--------------------|-----------------------------------------------------------------|
+| `web`              | Site public (carte Leaflet)                                     |
+| `admin`            | Back-office (nginx + reverse-proxy vers l'API)                  |
+| `api`              | API Fastify (public + routes admin), migrations DB              |
+| `crawler`          | Scraping incrémental/complet de Metal Archives via FlareSolverr |
+| `flaresolverr`     | Contournement Cloudflare (Chrome headless) pour le crawler      |
+| `geocoder-enqueue` | Peuple `band_locations` depuis `bands.location_text`            |
+| `geocoder-worker`  | Géocodage Geoapify                                              |
+| `groq-worker`      | Désambiguïsation LLM (Groq) des lieux non géocodés              |
+
+`crawler` et `flaresolverr` ne tournent **qu'en dev** pour l'instant : ils sont
+absents de `docker-compose.yml`. La prod partage la même base, alimentée depuis
+l'environnement de dev.
+
+## Déploiement
+
+- `docker-compose.yml` : production
+- `docker-compose.dev.yml` : environnement de dev (branche `dev`, auto-déployé
+  via webhook Forgejo → Coolify)
+
+Base PostgreSQL + PostGIS gérée séparément par Coolify. Variables d'env : voir
+`infra/.env.example`.
+
+## Qualité
+
+Le déploiement se déclenche sur webhook à chaque push : rien ne s'interpose
+entre `git push` et la mise en ligne. La porte de qualité est donc **locale**,
+et doit être installée une fois par clone :
+
+```
+npm install
+npm run hooks:install
+```
+
+| Commande                       | Portée                                                     |
+|--------------------------------|------------------------------------------------------------|
+| `npm run check`                | lint + types + tests JS + ruff + pytest (~6 s)             |
+| `npm run test:e2e`             | parcours Playwright du dashboard admin (~22 s)             |
+| `npm run test:integration:full`| SQL validé contre un vrai PostgreSQL+PostGIS (exige Docker)|
+| `npm run check:full`           | tout ci-dessus + mutation + audits de dépendances          |
+
+Le hook `pre-push` lance `check` puis `test:e2e`. `.forgejo/workflows/ci.yml`
+existe mais reste inerte tant qu'aucun runner Forgejo n'est enregistré.
+
+Outillage Python de test : `pip install -r requirements-dev.txt`.