Architecture Decision Records (ADR)

Trace pourquoi chaque choix structurant du dépôt — pas le comment (couvert par la documentation thématique sous docs/architecture/, docs/quality/ et docs/collaboration/), mais le contexte, l’alternative écartée et les conséquences assumées.

Format léger inspiré de Michael Nygard :

Contexte — ce qui a forcé une décision.
Décision — ce qui a été acté.
Statut — Accepted / Superseded by NNNN / Deprecated.
Conséquences — gain, prix à payer, garde-fous à connaître.

Chaque ADR est numéroté en séquence (NNNN-titre-en-kebab-case.md). Une fois acté, un ADR n’est pas réécrit : il est superseded par un nouvel ADR qui décrit la nouvelle posture et référence l’ancien.

Nouveau venu ? Le parcours thématique regroupe ces décisions par sujet et propose un tour cohérent — par où commencer, comment elles s’articulent. L’index ci-dessous reste la référence par numéro.

Frontière avec le cluster ? L’index des décisions système recense les ADR qui décrivent la frontière cluster ↔ atlas (préfixés CL-/AT- pour lever la collision des numéros entre les deux dépôts).

Index

#	Titre	Statut
0001	DevSecOps périmètre repo complet, périphérie sine die	Accepted
0002	Monorepo organisé en 8 catégories	Accepted
0003	`packages/logos` splitté en `assets/logos` + `cli/logos`	Accepted
0004	Volumes anonymes pour `sandbox/sillage-sandbox/`	Accepted
0005	Effect pour la programmation fonctionnelle	Accepted
0006	SvelteKit, Hono et Bootstrap comme socle	Accepted
0007	REDCap et Appwrite comme plateformes externes	Accepted
0008	CLIs thins, logique métier dans `packages/`	Accepted
0009	`atlas` source canonique vs `amarre` standalone	Accepted
0010	`node-appwrite` SDK 25.x conservé pour `TablesDB`	Accepted
0011	Trois paquets internes marqués `private`	Accepted
0012	Neutralisation du framing institutionnel	Accepted
0013	Documentation pour public non-expert, en français	Accepted
0014	Conventional Commits, scopes restreints	Accepted
0015	Hooks Git via lefthook, jamais bypassés	Accepted
0016	Branch protection sur `main`	Accepted
0017	Releases npm signées par OIDC sur deux registres	Accepted
0018	SLA de remédiation des findings sécurité	Accepted
0019	Dérogations explicites au workspace audit	Accepted
0020	Lint Svelte au preset strict	Accepted
0021	Politique de dépendances pour les sandboxes	Accepted
0022	Convention de nommage `atlas-` pour les paquets publiés	Accepted
0023	`storybook:build` cassé en amont (Storybook 10.4 / Svelte 5.55)	Accepted
0024	Ranges `~` sur les `dependencies` des paquets publiables	Accepted
0025	Documentation à plusieurs niveaux (surface, profondeur, inline)	Accepted
0026	Périmètre RGPD hors dépôt, questions ouvertes	Accepted
0027	Rôle de security champion : ouvert (vacant)	Accepted
0028	Documentation vérifiable : un miroir contrôlable du code	Accepted
0029	Pipeline de collaborations : architecture V1 (plateforme DataOps, contrat Parquet)	Accepted
0030	Profilage de collaborations : gate RGPD, base légale et droit d’opposition	Accepted
0031	Outil générique open-source : contribution inter-établissements	Amended by 0079
0032	KPI documentés : généré déterministe (diff-checké) vs snapshot (append-only)	Accepted
0033	Contrat d’interface entre l’application (`atlas`) et le cluster	Accepted
0034	CI adaptative par chemin : court-circuit des jobs lourds	Accepted
0035	Dépôt généraliste ouvert : neutralité de domaine	Accepted
0036	Migration de la documentation : VitePress → Astro Starlight	Accepted
0037	Retrait de la référence API générée (TypeDoc)	Accepted
0038	Épingler le niveau WCAG cible des tests d’accessibilité	Accepted
0039	Cadence d’audit transverse : trimestriel, rappel automatisé	Accepted
0040	Caches applicatifs : flux + backing-service injectable vs fichier local	Accepted
0041	Stratégie d’authentification du service CRF (Hono)	Accepted
0042	Périmètre des sandbox : dev/test local dans atlas, pas dans cluster	Accepted
0043	Publication des images de déploiement sur GHCR	Accepted
0045	Runtime Effect central par type de processus	Accepted
0046	Frontière Effect ↔ SvelteKit	Accepted
0047	Stratégie de validation (Effect Schema, zod en cohabitation)	Accepted
0048	Modèle d’erreur HTTP (atlas-errors conservé + couture Effect)	Accepted
0049	Convention de test Effect (it.effect, layers partagés, garde-fou)	Accepted
0050	Limite de l’audit knip face aux peerDependencies	Accepted
0051	Rétrospective du chantier socle Effect (E1–E14)	Accepted
0052	Charte rédactionnelle de la documentation (règles de relecture)	Accepted
0053	Merge commit imposé sur `main` (abandon du squash)	Accepted
0054	Ingestion massive OpenAlex par snapshot S3 (works + authors)	Accepted
0055	Catégorie dataops/ : code DataOps en Python natif	Accepted
0056	Registre de drifts : catalogue indexé des écarts révélés à l’exécution	Amended by 0071
0057	Reproductibilité : tests hermétiques et fixtures figées	Accepted
0058	Chargement de l’index (mart→Postgres) : report de `index_load` faute de producteur researchers	Accepted
0059	Producteur par chercheur : ancrage `author_id`, purge d’opposition au grain `(author_id, work_id)`	Accepted
0060	Consignation des reconnaissances multi-agents pré-implémentation	Accepted
0061	Accélérer la CI : cache de contenu, parallélisation des jobs, court-circuit élargi	Accepted
0062	MLOps niveau 1→2 : suivi de modèles, détection de dérive, réentraînement déclenché	Amended by 0079
0063	Échantillon cohérent par construction sur les petits bancs (authors dérivés des works)	Accepted
0064	Collecte « veille médiatique » (GKG v2) par pull HTTP incrémental, code-location dédié	Accepted
0065	Qualifier une organisation comme « université » : heuristique de nom + référentiel	Accepted
0066	Cache Turbo des checks dataops : package.json minimal et entrée dans le workspace	Accepted
0067	Modèle prédictif d’uplift FWCI sur EUNICoast (réorientation du pipeline citation)	Accepted
0068	Suivi de dérive du modèle d’uplift FWCI (drift applicatif, porte de sécurité)	Accepted
0069	Scan, signature et provenance des images conteneur publiées sur GHCR	Accepted
0070	Page de preuves (vitrine d’orientation) et doctrine des badges admissibles	Accepted
0071	Méta-gouvernance documentaire exécutable et cartographie de la couverture E2E	Accepted
0072	Tests basés sur les propriétés au dataops Python (Hypothesis)	Accepted
0073	Corriger le code, pas l’état, et garde-fou de cible de déploiement	Accepted
0074	Typologie documentaire d’intention (Diátaxis)	Accepted
0075	Déploiement prod par digest : atlas fournit les points d’injection, cluster les remplit	Accepted
0076	Portails d’orientation et accueil par intention	Amended by 0078
0077	Topologie : deux dépôts cluster & atlas, frontière outillée	Accepted
0078	Barre latérale thématique, navigation Diátaxis intra-catégorie	Accepted
0079	Boucle fermée dérive → réentraînement, active par défaut (citation)	Accepted
0080	Capture assistée des drifts au point d’échec	Accepted
0081	Modèle de prévision du volume d’articles par université (mediawatch)	Accepted
0082	Boucle fermée dérive → réentraînement, active par défaut (mediawatch)	Accepted
0083	Câblage d’OpenSSF Scorecard (note supply-chain et badge en tête)	Accepted
0084	Épinglage des images de base par digest (Pinned-Dependencies)	Accepted
0085	Cache de flux : package partagé Effect adossé à Postgres (CNPG)	Accepted
0086	Posture vis-à-vis des paliers Best Practices (silver visé, gold exclu)	Accepted
0087	Signature cosign des artefacts de Release GitHub	Accepted
0088	Portabilité : architectures (arm64/x86_64), OS et libc	Accepted
0089	Métriques Prometheus des services applicatifs (/metrics via Effect)	Accepted

Quand ouvrir un ADR

Un ADR se justifie quand :

la décision est durable (~ trimestres, pas semaines) ;
une alternative crédible a été écartée et le « pourquoi » se perdrait dans l’historique Git sans note explicite ;
une tension est assumée (compromis, dette acceptée, exception à une règle générale) que les contributeurs futurs doivent retrouver.

Un ADR n’est pas le bon endroit pour : une convention de code (→ docs/quality/code-style.md), un guide opérationnel (→ README de paquet), une décision opérationnelle court-terme ou un chantier actionnable (→ une issue GitHub, label enhancement ou tech-debt).