Files

T

Johan LEROY 4c72fbbb69 docs: fonde les vues d'architecture du monorepo

Cinq vues Mermaid dans docs/architecture (vue d'ensemble, infra, backend,
frontend, donnees), plus leur index, les conventions de statut et la regle
de maintenance en PR.

Reprend les jalons J1-J4, disparus de dev lors de la reecriture du README
(2670483) et restes seulement sur main : plus rien sur la branche de travail
ne disait ce que le projet doit prouver.

Fige les decisions du module Terraform k3s, qui ne vivaient jusqu'ici que
dans des commentaires de code et des description de variables : version
epinglee obligatoire, Traefik desactive, kubeconfig en 600/root, state local.

Corrige trois affirmations devenues fausses : le frontend classe
"a initialiser" alors que le squelette existe depuis 49f4697, le port 4200
dit attendu par docker-compose.yml qui n'a aucun service frontend, et
l'arborescence core/ prescrite par TESTING.md sans exister.

2026-09-15 11:56:18 +02:00

2.3 KiB

Raw Permalink Blame History

Architecture

Les vues d'architecture d'EnerVision. Un ADR (../adr/) décide et date une décision structurante ; une vue d'architecture décrit le système qui en résulte. Quand les deux se contredisent, c'est l'ADR qui fait foi et la vue qui est en retard.

Les documents

Document	Ce qu'il couvre
00-vue-ensemble.md	Jalons du projet, contexte, conteneurs, sécurité, flux bout en bout
10-infra.md	Poste de développement, cible k3s, décisions figées, ports et noms
20-backend.md	Couches FastAPI, séquence de démarrage, routes, configuration
30-frontend.md	Angular, arborescence cible, flux HTTP
40-data.md	Frontières `db/` et `alembic/`, cycle de vie d'une mesure, modèle

L'observabilité, la sécurité et la CI/CD n'ont pas de document propre : ce sont des sections des cinq ci-dessus, tant que monitoring/, .github/workflows/ et etl/airflow/ ne contiennent que des .gitkeep. Elles en sortiront le jour où elles auront de la matière. Un fichier vide de plus n'aide personne.

Conventions

Mermaid, et rien d'autre

GitHub rend Mermaid nativement dans les fichiers .md. Un diagramme est donc du texte : il se relit en revue, il se diffe, et il ne se périme pas dans un binaire que plus personne ne sait rouvrir six mois plus tard. Aucune image exportée, aucun .drawio, aucun .png.

Chaque section porte son statut

Une large part de la stack n'est pas écrite. Une vue qui mélange l'existant et la cible sans le dire devient fausse sans prévenir.

Statut	Sens
`Fait`	Le code existe et tourne
`En cours`	Commencé, incomplet
`Cible`	Décidé, pas encore écrit

Légende des diagrammes

Trait plein pour ce qui tourne, trait pointillé pour ce qui est cible.

flowchart LR
  A[Composant en place] --> B[Composant en place]
  B -.-> C[Composant cible]

Maintenance

Toute PR qui change un composant met à jour sa vue dans la même PR. Une vue qu'on promet de mettre à jour plus tard ne l'est jamais.

Une documentation fausse coûte plus cher qu'une documentation absente : on la lit, on la croit, et on construit dessus. Si une section ne peut plus être tenue à jour, elle est supprimée plutôt que laissée à dériver.

2.3 KiB Raw Permalink Blame History