Parcours thématique des décisions

Cette page propose un tour cohérent des décisions du dépôt, regroupées par thème plutôt que par numéro. Elle s’adresse à un nouveau venu : plutôt que de lire les 88 ADR dans l’ordre chronologique, suis le fil ci-dessous pour comprendre pourquoi le dépôt est fait comme il est.

Pour la liste exhaustive par numéro (et le statut de chacun), voir l’index. Pour le quand ouvrir un ADR, voir la fin de l’index.

Par où commencer ? Si tu ne lis que trois décisions, lis 0002 (comment le dépôt est organisé), 0035 (ce que le dépôt cherche à être) et 0028 (comment la documentation reste fiable).

1. Ce que le dépôt cherche à être

Les décisions de vocation : à qui s’adresse le dépôt, et quelle posture il adopte. À lire en premier — elles éclairent toutes les autres.

En résumé. Cette section pose ce que le dépôt veut être. La décision-chapeau est 0035 : Atlas est un dépôt généraliste et ouvert, et tout ce qui y est produit (code, documentation, identifiants, ADR) reste neutre vis-à-vis d’un domaine, d’une marque et d’un établissement, pour qu’un contributeur de n’importe quel horizon puisse le reprendre. 0031 en décline le versant outil — un logiciel générique et multi-tenant, pensé pour la contribution inter-établissements — et 0012 le versant éditorial — un ton factuel, sans positionnement promotionnel ni framing institutionnel. Les trois disent la même posture sous trois angles ; 0035 est le principe directeur, 0031 et 0012 ses applications.

• 0035 — Dépôt généraliste ouvert : la règle-chapeau. Atlas est généraliste et ouvert ; tout y reste neutre de domaine, de marque et d’établissement.
• 0031 — Outil générique open-source : l’outil est multi-tenant, pensé pour la contribution inter-établissements.
• 0012 — Neutralisation du framing institutionnel : ton factuel, pas de positionnement promotionnel.

2. Comment le code est organisé

La structure du monorepo : son découpage, ses frontières, ses conventions de nommage. (Un monorepo est un dépôt unique qui héberge plusieurs sous-projets au lieu d’un dépôt par projet.)

En résumé. La colonne vertébrale est 0002 : le dépôt est découpé en huit catégories, chacune avec ses propres règles, ce qui fixe où va chaque sous-projet. Sur ce squelette se greffent des règles de placement et de nommage : la logique métier vit dans packages/, les CLI (outils en ligne de commande) restent minces et s’y adossent (0008) ; atlas est la source canonique dont l’app standalone amarre est dérivée (0009). Côté publication, les paquets purement internes sont marqués private (0011) et ceux qui sont publiés suivent la convention de nommage atlas- (0022). 0003 sert d’exemple concret : un paquet scindé entre catégorie assets et catégorie cli pour respecter ces frontières. 0055 amende 0002 en ajoutant une 9e catégorie dataops/ : le code DataOps (Dagster, dbt) y vit en Python natif, hors du paradigme Node/TypeScript — et précise du même coup que 0008 (logique dans packages/) et 0005 (Effect) ne portent que sur le périmètre TypeScript.

• 0002 — Monorepo en 8 catégories : la colonne vertébrale — chaque sous-projet a une catégorie et des règles propres.
• 0055 — Catégorie dataops/ (Python natif) : la 9e catégorie, pour le code DataOps (Dagster/dbt), hors du graphe Node/TypeScript.
• 0066 — Cache Turbo des checks dataops : amende 0055 sur le seul point « aucun package.json » — les code-locations reçoivent un package.json privé minimal pour entrer dans le cache Turbo (skip des checks Python inchangés), sans devenir des paquets Node.
• 0008 — CLIs thins, logique dans packages/ : où vit la logique métier.
• 0009 — atlas source canonique vs amarre : l’articulation entre le dépôt et une app standalone.
• 0011 — Paquets internes private et 0022 — Convention de nommage atlas- : ce qui est publié, et sous quel nom.
• 0003 — logos splitté assets + CLI : un exemple concret d’application des règles de catégorie.

3. La stack technique

Les choix de technologies et leurs raisons — dont quelques contraintes subies plutôt que choisies.

En résumé. Le paradigme du code métier est Effect, une bibliothèque de programmation fonctionnelle pour TypeScript (0005) ; un cadrage de 2026-06 l’étend de simple « langage de description » à véritable couche d’exécution, détaillé dans six ADR de socle — runtime central (0045), frontière avec SvelteKit (0046), stratégie de validation (0047), modèle d’erreur HTTP (0048), convention de test (0049) et limite de l’audit knip (0050). Le socle applicatif retient SvelteKit (front), Hono (API) et Bootstrap (UI) (0006), et deux plateformes externes sont intégrées (0007). Plusieurs décisions ici ne sont pas des choix mais des contraintes assumées : un SDK figé en 25.x (0010), un lint Svelte volontairement strict (0020), des ranges de versions ~ sur les paquets publiables (0024) et une dette amont sur storybook:build, documentée pour éviter de la rechercher en vain (0023).

• 0005 — Effect pour la programmation fonctionnelle : le paradigme du code métier.
  • Socle d’exécution Effect (cadrage 2026-06, étend 0005 de « langage de description » à « couche d’exécution » — voir le plan de résorption) : 0045 — runtime central (où le code s’exécute), 0046 — frontière SvelteKit (où Effect s’arrête), 0047 — validation Schema/zod, 0048 — modèle d’erreur HTTP (atlas-errors conservé), 0049 — convention de test (it.effect), 0050 — limite knip peer-deps.
• 0006 — SvelteKit, Hono, Bootstrap : le socle applicatif.
• 0007 — REDCap et Appwrite : les plateformes externes intégrées.
• 0010 — node-appwrite SDK 25.x, 0020 — Lint Svelte strict, 0024 — Ranges ~ sur les paquets publiables : des contraintes de versions assumées.
• 0023 — storybook:build cassé en amont : une dette subie, documentée pour ne pas la rechercher en vain.

4. La chaîne de qualité et de sécurité

Le DevSecOps : ce qui garantit qu’une modification ne casse rien et reste sûre. (Le DevSecOps intègre la sécurité directement dans la chaîne de développement et de livraison.) C’est le cœur de la crédibilité du dépôt public.

En résumé. Le périmètre est cadré par 0001 : le chantier est complet côté dépôt, et les neuf items dépendant d’une coordination externe sont reportés sine die, chacun avec son bloquant. La discipline de contribution est posée et jamais contournée : Conventional Commits à scopes restreints (0014), hooks Git via lefthook (0015), et branch protection sur main (0016) ; la CI s’allège selon les chemins modifiés sans affaiblir cette protection (0034). La publication des paquets est signée par OIDC sur deux registres (0017). La posture de réponse sécurité fixe un SLA de remédiation des findings (alertes des outils d’analyse) (0018) et acte que le rôle de security champion reste vacant (0027) ; toute exception aux règles se trace explicitement (0019). Enfin, un volet cloud-native (12-factor) : auditer régulièrement (0039), rendre les caches partageables via un backing-service plutôt qu’un fichier local (0040) et authentifier le service CRF (0041).

• 0001 — DevSecOps périmètre repo complet : l’ambition de couverture, et ce qui est reporté.
• 0014 — Conventional Commits, 0015 — Hooks Git via lefthook, 0016 — Branch protection sur main : la discipline de contribution, jamais contournée.
• 0034 — CI adaptative par chemin : comment la CI s’allège sans casser la branch protection.
• 0017 — Releases OIDC sur deux registres : la publication signée.
• 0018 — SLA de remédiation des findings, 0027 — Security champion (vacant) : la posture de réponse sécurité.
• 0019 — Dérogations au workspace audit : comment une exception aux règles se trace.
• 0039 — Cadence d’audit transverse, 0040 — Caches : flux + backing-service, 0041 — Authentification du service CRF : le durcissement cloud-native (12-factor) — auditer régulièrement, rendre les caches partageables et les services authentifiés.
• 0056 — Registre de drifts : capitaliser les écarts révélés à l’exécution (que le lint ne voit pas) et les pièges de revue, dans un catalogue indexé et citable.
• 0080 — Capture assistée des drifts au point d’échec : outille la saisie du registre 0056 sans en changer la décision — un capteur (reporter Playwright, hook pytest) dépose à chaud un brouillon gitignoré sur échec d’un run, qu’un humain promeut ensuite via pnpm drift:new (issue de suivi créée, identifiant calculé). Le jugement « marquant » reste humain.
• 0061 — Accélérer la CI : rendre le pipeline de qualité rapide sans le rendre laxiste — cache de contenu, parallélisation des jobs, court-circuit élargi (skip des jobs sans fichier concerné), workflows validés par actionlint.
• 0057 — Reproductibilité : tests hermétiques : un test ne dépend ni du réseau ni de l’état machine — fixtures figées, images par digest, déterminisme du pipeline (vérifie le sha256 du contrat).
• 0058 — Report de index_load : on ne livre pas un chargement d’index à demi (pairs sans la recherche researchers) — l’asset attend un producteur de données par chercheur servi, le vrai débloqueur (même gap capacité/producteur que works/authorships).
• 0059 — Producteur par chercheur, ancrage author_id : le producteur que 0058 attendait, dérivé du seul brut S3 (reproductible), ancré sur un identifiant imparfait (author_id — plusieurs par personne, publications bruitées). La purge d’opposition est donc chirurgicale au grain (author_id, work_id) validé : on ne retire que ce que la personne revendique, jamais une publication d’autrui. Le mart conserve une provenance par publication (capacité de purge) ; la validation chercheur et la liste d’opposition relèvent du déployeur.

5. La documentation comme miroir du code

La politique de documentation : pour qui on écrit, à quels niveaux, et comment on empêche la doc de mentir.

En résumé. Le lecteur visé et la langue sont fixés par 0013 : on écrit en français pour un public non-expert. 0025 organise l’écriture en trois niveaux (surface, profondeur, inline) pour servir à la fois le néophyte et l’expert. Le principe anti-mensonge est 0028 : la doc est un miroir contrôlable du code — ce qui est dérivable du code est généré et vérifié en CI, le reste est audité (présence, liens, cohérence), de sorte qu’une dérive casse la CI. 0032 en précise la mécanique pour les indicateurs : distinguer le contenu généré déterministe (vérifié par diff) du snapshot (append-only) pour historiser sans rendre la CI instable. Enfin 0036 documente l’outil qui construit cette documentation (migration VitePress → Astro Starlight) et pourquoi on en a changé.

• 0013 — Documentation FR pour public non-expert : la langue et le public.
• 0025 — Documentation à plusieurs niveaux : surface, profondeur, inline.
• 0028 — Documentation vérifiable : la doc est un miroir contrôlable ; toute dérive casse la CI.
• 0032 — KPI : généré déterministe vs snapshot : comment historiser des indicateurs sans rendre la CI instable.
• 0036 — Migration VitePress → Astro Starlight : l’outil qui construit la documentation, et pourquoi on en change.
• 0074 — Typologie documentaire d’intention (Diátaxis) : un troisième axe (apprendre, faire, consulter, comprendre) pour ranger chaque page par le besoin de lecture qu’elle sert.
• 0076 — Portails d’orientation et accueil par intention : un accueil qui met en avant le bilan vérifiable (et, à l’origine, deux pages-portails retirés depuis — voir 0078). Le patron « pointer, pas recopier » reste en vigueur.
• 0078 — Barre latérale thématique, navigation Diátaxis intra-catégorie : la navigation revient par thème (le découpage par intention éclatait les sujets) ; Diátaxis reste un principe de rédaction, matérialisé par l’ordre des pages dans chaque catégorie. Amende 0076 (retire ses portails).
• 0060 — Consignation des reconnaissances multi-agents : le cheminement vérifié qui mène à une décision — la cartographie du terrain conduite avant un lot structurant — est consigné sous docs/audit/, distinct de l’audit transverse trimestriel (0039). On garde ainsi le pourquoi d’une forme de code, pas seulement son quoi.

6. Le pipeline de collaborations (le grand projet)

Le chantier applicatif central : transformer des données de citations en recommandations de collaboration, à travers une plateforme DataOps. (Le DataOps applique au traitement de données les pratiques d’automatisation et de qualité du DevOps.)

En résumé. 0029 pose l’architecture V1 : une plateforme DataOps alignée sur les standards du marché (lakehouse Parquet + DuckDB, transformations dbt, orchestration Dagster, qualité de données, index PostgreSQL/pgvector pour l’exploration), un flux mensuel qui va des citations brutes aux paires de chercheurs et leurs features. Le contrat producteur ↔ consommateur reste Parquet + manifest, et les fonctionnalités les plus avancées (LLM génératif notamment) sont renvoyées à un palier 2. 0033 tient le contrat d’interface entre l’application atlas et le cluster qui l’exploite : il est la source de vérité unique des points de contact (stockage objet S3, base PostgreSQL/pgvector, orchestrateur, lineage, exposition…), fixe les conventions et formats mais pas les valeurs propres à une instance, et impose que tout changement d’un point de contact se reflète dans la même pull request que le code ou l’infrastructure concernés. 0054 amende 0029 sur l’ingestion : pour couvrir toute la base OpenAlex (works + authors), la source devient le snapshot S3 (copie complète exportée, synchronisée de façon incrémentale par date), l’API REST étant reléguée aux compléments ciblés.

• 0029 — Architecture V1 du pipeline : la plateforme DataOps et le contrat Parquet.
• 0033 — Contrat d’interface application ↔ cluster : la frontière entre le code applicatif et l’infrastructure.
• 0077 — Topologie : deux dépôts cluster & atlas : pourquoi on garde deux dépôts (on ne fusionne pas, pas de 3ᵉ dépôt doc ni Python) et on outille la frontière plutôt que de la subir.
• 0054 — Ingestion massive par snapshot S3 : toute la base OpenAlex (works + authors), incrémentale, en remplacement de l’API REST.
• 0067 — Modèle prédictif d’uplift FWCI sur EUNICoast : réoriente la finalité de citation — au-delà des citations croisées, prédire la valeur ajoutée d’une collaboration (FWCI collab − solo) depuis les thématiques (jamais l’identité), pour recommander auteurs/thématiques sur le réseau EUNICoast.
• 0068 — Suivi de dérive du modèle d’uplift FWCI : surveille la dérive du modèle (distribution des uplift, R²/MAE honnêtes, couverture embedding) — informatif, sauf la bascule predictive → descriptive qui bloque (perte totale de pouvoir prédictif). Réutilise le drift d’embeddings (ADR 0062).
• 0079 — Boucle fermée dérive → réentraînement, active par défaut : ferme la boucle MLOps de citation — la dérive mesurée déclenche le réentraînement, automatiquement et par défaut (le déployeur désarme, ne arme plus). Borné par une condition de donnée neuve (terminaison prouvée). Amende 0062 (STOPPED → RUNNING pour ce seul sensor) et 0031 (autonomie par défaut, opt-out).
• 0064 — Collecte « veille médiatique » (GKG v2) : une seconde source dans un code-location dédié (mediawatch) — pull HTTP incrémental des fichiers 15 minutes de GDELT, sans dépendance Google Cloud, multilingue natif.
• 0065 — Qualifier une organisation comme « université » : GKG ne type pas les organisations — la qualification se fait par heuristique de nom multilingue + référentiel d’établissements faisant foi.
• 0081 — Modèle de prévision du volume d’articles (mediawatch) : mediawatch passe de la description à la prévision — un modèle global (un seul pour toutes les universités, identité encodée en feature) prédit le volume futur à semaine/mois/trimestre, validé honnêtement dans le temps (pas de fuite) avec la porte prédictif/descriptif de 0067. Donne à mediawatch sa première instrumentation MLOps (MLflow + drift), donc un signal de dérive — la porte vers son CT autonome (0079).
• 0082 — Boucle fermée dérive → réentraînement (mediawatch) : généralise 0079 à mediawatch, maintenant qu’il a un signal de dérive (0081). Même patron (sensor actif par défaut, opt-out, terminaison prouvée), mais le garde-fou « donnée neuve » se fonde sur l’avancée des partitions GKG ingérées (≠ le watermark de citation). Les deux pipelines ont désormais un CT autonome homogène.

7. Données personnelles et conformité

Le RGPD : ce qui relève du dépôt et ce qui relève de chaque déployeur.

En résumé. 0026 trace la ligne de partage : l’institutionnel (validation des bases légales, désignation du responsable de traitement) reste hors dépôt et relève de chaque établissement exploitant ; le dépôt ne décide pas à leur place. 0030 rouvre ce cadre pour le cas précis du profilage de collaborations et tranche les bornes techniques côté code : un traitement en opt-out fondé sur une base légale d’intérêt public (à confirmer par le DPO de l’établissement), où la déclaration d’alliances par l’utilisateur filtre l’affichage et non l’ingestion, et où le droit d’opposition (art. 21) retire effectivement une personne du mart et de l’index. Les deux ne se contredisent pas : 0030 outille, côté code, ce que 0026 laisse à l’exploitant.

• 0026 — Périmètre RGPD hors dépôt : ce que le dépôt ne décide pas.
• 0030 — Profilage de collaborations : gate RGPD : base légale, droit d’opposition, responsabilité de l’exploitant.

8. Exceptions et dette assumées

Des décisions ponctuelles : un cas particulier, une politique locale, une dette qu’on choisit de porter en connaissance de cause.

En résumé. Ces décisions n’ont pas de portée transverse ; elles tranchent un cas local en l’assumant. 0004 retient des volumes anonymes pour la sandbox sillage-sandbox, un choix d’isolation propre à cet environnement. 0021 assouplit la politique de dépendances dans les sandboxes, là où le risque est contenu et où la rigueur appliquée au reste du dépôt serait disproportionnée.

• 0004 — Volumes anonymes pour sillage-sandbox : un choix d’isolation spécifique.
• 0021 — Politique de dépendances des sandboxes : des règles assouplies là où le risque est contenu.

Plusieurs ADR apparaissent dans plus d’un thème (par exemple 0031 touche à la vocation et au RGPD, 0030 au pipeline et à la conformité) : c’est normal, une décision structurante rayonne sur plusieurs sujets. Le classement ci-dessus privilégie l’angle le plus utile à un premier parcours.