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

5.4 KiB

Raw Blame History

Vue d'ensemble

EnerVision collecte, stocke, analyse et restitue des séries temporelles énergétiques, sur une machine on-premise.

Cadre du projet

Quatre jalons ont été posés à l'ouverture du projet. Ils ont disparu du README.md lors de la réécriture de l'arborescence (2670483) et ne subsistaient que sur main. Ils sont repris ici parce qu'ils disent ce que le projet doit prouver, et donc à quoi sert chaque décision technique.

Jalon	Intitulé	Ce que la documentation apporte
J1	Valider la préparation de l'environnement et du repo	`10-infra.md` décrit la stack du poste de développement et la commande qui la démarre
J2	Valider le périmètre retenu et les choix technologiques	Les ADR (`../adr/`) portent les choix ; `40-data.md` liste les questions de périmètre encore ouvertes
J3	Valider l'architecture et la gestion de la sécurité	Les cinq vues, et la section « Sécurité » ci-dessous qui consolide les surfaces exposées
J4	Valider la robustesse et assurer les livrables	`20-backend.md` et `30-frontend.md` renvoient aux conventions de tests de chaque application

Contexte

Statut : Cible. Les acteurs et les sources de mesures ne sont pas arrêtés, c'est l'objet du jalon J2.

flowchart LR
  exploitant["Exploitant<br/>consulte les courbes"]
  admin["Administrateur<br/>exploite la plateforme"]
  sources["Sources de mesures<br/>à définir en J2"]

  subgraph systeme["EnerVision"]
    plateforme["Collecte, stockage,<br/>analyse et restitution<br/>de séries temporelles"]
  end

  sources -.-> plateforme
  exploitant -.-> plateforme
  admin -.-> plateforme

Conteneurs

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

flowchart TB
  navigateur["Navigateur"]

  subgraph machine["Machine on-premise"]
    front["Frontend Angular 22<br/>apps/frontend"]
    api["API FastAPI<br/>apps/backend"]
    db[("PostgreSQL 17<br/>TimescaleDB")]
    airflow["Airflow<br/>etl/airflow"]
    prom["Prometheus"]
    grafana["Grafana"]
  end

  navigateur --> front
  front -.-> api
  api --> db
  airflow -.-> db
  prom -.-> api
  grafana -.-> db
  grafana -.-> prom

Le lien front -.-> api est en pointillé à dessein : le frontend n'appelle aujourd'hui aucune API, provideHttpClient n'est pas encore installé. Voir 30-frontend.md.

Le lien prom -.-> api de même : l'API expose bien /metrics au format Prometheus, mais aucun collecteur ne vient le lire.

État de la stack

Domaine	Technologie	Emplacement	Statut	Ce qui existe réellement
Backend	FastAPI, Python 3.14	`apps/backend`	`En cours`	Factory, configuration, journalisation, 2 sondes de santé, `/metrics`. Aucune couche métier
Frontend	Angular 22, Node 24	`apps/frontend`	`En cours`	Squelette `ng new` standalone, routes vides, aucun service HTTP
Base	PostgreSQL 17 + TimescaleDB	`db`	`Fait`	Bootstrap de l'extension, base de test, chaîne Alembic. Aucune table applicative
Infra	Terraform, k3s single-node	`infra/terraform`	`En cours`	Module d'installation du cluster. Jamais appliqué, aucune ressource Kubernetes déclarée
Monitoring	Prometheus, Grafana, Alertmanager	`monitoring`	`Cible`	Rien, hors le `/metrics` exposé par l'API
ETL	Apache Airflow	`etl/airflow`	`Cible`	Rien
CI/CD	GitHub Actions	`.github/workflows`	`Cible`	Rien

Flux bout en bout

Statut : Cible. Aucun maillon de cette chaîne n'existe aujourd'hui, à l'exception de la base.

sequenceDiagram
  participant S as Source de mesures
  participant A as Airflow
  participant T as TimescaleDB
  participant API as FastAPI
  participant U as Angular

  S->>A: mesures horodatées
  A->>T: insertion dans l'hypertable
  T->>T: rafraîchissement de l'agrégat continu
  U->>API: GET /api/v1/...
  API->>T: agrégation sur la fenêtre demandée
  T-->>API: lignes
  API-->>U: JSON

Sécurité

Section rattachée au jalon J3. Le détail par brique est dans chaque document ; voici la vue consolidée.

En place

Les secrets n'ont pas de valeur par défaut. APP_SECRET_KEY et DATABASE_URL sont requis sans repli : l'application refuse de démarrer si l'un manque, plutôt que de tourner avec une valeur de démonstration. .env reste hors dépôt, .env.example est versionné.
CORS conditionnel : le middleware n'est ajouté que si APP_CORS_ORIGINS est renseigné.
Documentation interactive fermée en production : /docs, /redoc et /openapi.json sont désactivés dès que APP_ENV=prod.
Conteneur backend non-root, déclaré dans apps/backend/Dockerfile.
Côté infrastructure : la clé SSH est marquée sensitive, le kubeconfig reste en 600/root sur la machine cible et n'est lu que par sudo, *.tfvars est ignoré par git sauf les .example.

Absent

Aucune authentification ni autorisation. Les deux endpoints exposés sont publics. Rien n'est encore décidé sur ce point.
Pas de TLS, pas de limitation de débit, pas de journalisation des accès, pas de rotation des secrets.
Aucune analyse de dépendances ni de conteneur, faute de CI.

Décisions structurantes

Elles vivent dans ../adr/, pas ici.

ADR	Objet
0001	PostgreSQL 17 avec l'extension TimescaleDB, et la frontière `db/` vs `alembic/`

5.4 KiB Raw Blame History