§9 — Décisions architecturales¶
Les 14 ADR du projet, classées par ordre chronologique et par numéro (qui reflète l'ordre temporel). Chaque ADR suit la même structure : Date / Statut / Implémentation (hashes) / Contexte / Décision / Conséquences (Positives / Négatives / Trade-offs assumés) / Alternatives écartées / Références.
Tableau récapitulatif¶
| # | Titre | Statut | Date | 1-line résumé |
|---|---|---|---|---|
| ADR-001 | Stack TypeScript unique (monostack) | Acceptée | 2026-04-18 | Un seul langage côté code produit (Vue + Fastify + Prisma), pas de Python |
| ADR-002 | Méthodologie ABEM pour le CSS | Acceptée | 2026-04-18 | Préfixes a-/m-/o-/t-/p- sur 100 % des composants Vue |
| ADR-003 | Monolithe Fastify vs microservices | Acceptée | 2026-04-18 | API + cron ingestion dans le même runtime, pas de queue |
| ADR-004 | Prisma comme ORM | Acceptée | 2026-04-18 | Schéma typé end-to-end, migrations versionnées, zéro SQL brut |
| ADR-005 | Leaflet pour la cartographie | Acceptée avec drift | 2026-04-18 | Leaflet + OSM (drift vs swisstopo WMTS initial pour zero-cost attribution) |
| ADR-006 | D3 vanilla vs wrappers Vue | Acceptée | 2026-04-18 | D3 modules directement, pas de lib wrapper, logique pure extraite |
| ADR-007 | LINDAS SPARQL comme source de données | Acceptée — pivot | 2026-04-20 | Pivot depuis XML OFEV en J4, flux hydroweb.xml mort |
| ADR-008 | Transparence du sourcing des stations CREALP | Acceptée — implémentée | 2026-04-22 | Champ sourcingStatus CONFIRMED / ILLUSTRATIVE orthogonal à dataSource |
| ADR-009 | Périmètre Storybook et exclusions | Acceptée — implémentée | 2026-04-23 | 15 composants storyisés, 3 organismes Pinia + Leaflet exclus |
| ADR-010 | Architecture frontend post-refactor | Acceptée — implémentée | 2026-04-23 | Façades feature-grouped, lib/ domain-scoped, règles enforced |
| ADR-011 | Infrastructure de documentation arc42 | Acceptée — implémentée | 2026-04-24 | Site MkDocs Material sur docs.alpimonitor.fr, 10 sections, C4 Structurizr, deploy Coolify |
| ADR-012 | Introduction d'une couche IA | Acceptée — A+D+B+C livrées | 2026-06-04 | Narration LLM (Mistral) + observabilité LLM maison (LiteLLM-ready, non déployé) + détection d'anomalie statistique déseasonnalisée + chat par function-calling sur 4 fonctions (QueryPort) ; en échec en prod depuis le 2026-09-07, cf. constats |
| ADR-013 | Extension au domaine énergétique (tarifs ElCom) | Acceptée — implémentée | 2026-09-27 | Tarifs ElCom via LINDAS dans des tables dédiées (migrations additives), import manuel hors cron, positionnement d'un gestionnaire sur quatre bases de comparaison |
| ADR-014 | Plateforme à deux domaines : accueil et navigation | Acceptée — implémentée et en production | 2026-09-28 | Accueil sur / (méthode + une carte par domaine avec un chiffre daté), hydrologie sur /hydrologie, barre de navigation commune ; « Multi-pages » devient « Pages de détail » |
Notes de lecture¶
Chaque note date de l'écriture de l'ADR qu'elle commente ; elles ne sont pas réécrites après coup. Le statut à jour est celui du tableau ci-dessus.
- ADR-005 a un drift documenté — la décision initiale visait swisstopo WMTS, la réalité tourne sur OpenStreetMap (stabilité + zero-cost attribution). Trace conservée, pas de superseded.
- ADR-007 est un pivot structurant — survenu en cours de sprint (J4), il a invalidé toute la section ingestion du PRD initial. L'API, le modèle de données, et les conventions de sourcing en héritent.
- ADR-008, ADR-010, ADR-011 sont les plus récents — ils capturent les décisions post-livraison candidature (session Option A + refactor post-Storybook + documentation arc42). Leur densité narrative est la plus élevée du corpus.
- ADR-012 cadre la couche IA : extensions A (narration Mistral) + D (observabilité LLM maison) + B (anomalie statistique) livrées (A+D sur
feat/ai-layer, B surfeat/ai-anomaly) ; seule C (chat/RAG) reste proposée. D livre une observabilité réelle (décorateur →LlmCallRun,/ai/status) ; le proxy LiteLLM est ready mais non déployé (point d'extension assumé). B est statistique, pas LLM : z-score déseasonnalisé par heure-de-jour (apps/api/src/anomaly/), scan isolé post-ingestion,Alertréactivé sans migration. C'est avec C que l'« hexagonal » deviendra un objectif réel et localisé (frontière port/adapter). Le statut reflète explicitement le livré vs le à venir. (Depuis : C livrée et en production, tagsv1.4.0-chat-apiàv1.6.0-docs.) - ADR-013 étend le projet à un second domaine — tarifs d'électricité de l'ElCom, consommés par le même service LINDAS que l'hydrologie. Le schéma énergétique vit dans ses propres tables, ajoutées par migrations additives : aucune table hydrologique n'est modifiée. L'import est une commande manuelle, jamais lancée au démarrage ni par cron. Migrations et import ont été rejoués sur une copie de la base de production avant le merge.
- Historique git réécrit le 2026-09-28 : les identifiants de commit antérieurs ont été mis à jour.
- Historique git réécrit une seconde fois le 2026-09-29 : les identifiants de commit antérieurs ont été mis à jour.
Les sources des ADR sont dans le dépôt, sous docs/09-architectural-decisions/. Les versions d'avant la migration arc42 (ADR-001 à ADR-011) restent gelées sous docs/_legacy/architecture/adr/, pour traçabilité.