EnerVision

Monorepo de la plateforme EnerVision : collecte, stockage, analyse et restitution de series temporelles energetiques, deployee sur une machine on-premise.

Jalons

Jalon	Intitulé
J1	Valider la préparation de l'environnement et du repo
J2	Valider le périmètre retenu et les choix technologiques
J3	Ingestion & backend
J4	Architecture, sécurité & frontend
J5	Valider la robustesse et assurer les livrables
J6	Amélioration possible

Ce que la documentation apporte à chacun : docs/architecture/00-vue-ensemble.md.

Stack

Domaine	Technologie	Emplacement	Etat
Backend	FastAPI, Python 3.14	apps/backend	En place
Frontend	Angular 22, Node 26	apps/frontend	En place
Base	PostgreSQL 17 + TimescaleDB	db	En place
ETL	Apache Airflow	etl/airflow	Sept DAGs
Infra	Terraform (VM ENI ; module k3s)	infra/terraform	VM appliquée, k3s écrit non appliqué
Reverse proxy	Nginx, TLS, frontal SNI	infra/proxy, infra/front	En place, certificats Let's Encrypt
CI/CD	GitHub Actions	.github/workflows	En place
Monitoring	Prometheus, Grafana, Alertmanager	monitoring	En place, profil Compose
Stockage objet	Garage (S3), un par environnement	infra/garage	En place, archives de reading
Tests e2e et de charge	Playwright, k6	tests	En place
ML	LightGBM, MLflow	ml	En place

Toutes ces briques tournent sur la machine du groupe, en trois environnements (production, recette, dev). Le frontend sert le tableau de bord, les vues sites, recommandations et supervision des capteurs, toutes branchées sur l'API réelle : les fixtures sont coupées (useMockFixtures: false). Le module Terraform k3s reste une cible, écrite et validée, jamais appliquée.

L'etat detaille de chaque brique et les vues d'architecture sont dans docs/architecture.

Arborescence

.
├── apps/
│   ├── backend/        API FastAPI
│   └── frontend/       Application Angular
├── db/
│   ├── init/           Bootstrap PostgreSQL + TimescaleDB
│   ├── migrations/     Migrations SQL versionnees
│   ├── roles/          Roles PostgreSQL hors schema (supervision)
│   └── seeds/          Jeu de demonstration des tests
├── etl/airflow/
│   ├── dags/           DAGs d'orchestration (pipeline ML, alertes, imports, dérive, rétention)
│   ├── plugins/        Operateurs et hooks maison
│   ├── include/        Requetes SQL et ressources des DAGs
│   └── tests/          Tests d'integrite des DAGs
├── infra/
│   ├── front/          Frontal SNI de la machine : ports 80 et 443, aiguillage par nom
│   ├── garage/         Stockage objet S3 : configuration sans secret
│   ├── proxy/          Reverse proxy Nginx : terminaison TLS et routage
│   └── terraform/
│       ├── modules/        Modules reutilisables
│       └── environments/   Racines Terraform, une par environnement
├── ml/                 Pipeline d'entrainement LightGBM, suivi MLflow
├── monitoring/
│   ├── prometheus/     Collecte et regles d'alerte
│   ├── grafana/        Provisioning et dashboards
│   └── alertmanager/   Routage des alertes
├── tests/
│   ├── e2e/            Parcours Playwright contre la stack
│   ├── garage/         Tests de fumée S3 joués par la CI contre Garage
│   └── load/           Scenarios de charge k6
├── docs/               ADR, vues d'architecture, runbook de pilotage, livrables de rendu
└── scripts/            Outillage local

Demarrage

Prerequis : uv, Docker, Node 26 (version de la CI et de l'image frontend, npm fourni). Le poste doit disposer de Python 3.14, que uv installe seul.

cp .env.example .env                               # variables de docker-compose
cp apps/backend/.env.example apps/backend/.env     # variables du backend hors conteneur

make install   # dependances du backend, du frontend, du ML et des DAGs
make dev       # toute la stack, voir ci-dessous
make check     # lint + typage + tests

make dev enchaine tout : demarrage des services conteneurises (base sur le port 5433, Mailpit, Airflow), migrations Alembic, peuplement de demonstration si les alertes manquent, puis backend et frontend en rechargement a chaud sur le poste.

Service	Adresse
Backend	http://localhost:8000 (documentation sur /docs)
Frontend	http://localhost:4200
Airflow	http://localhost:8080 (AIRFLOW_ADMIN_USERNAME / AIRFLOW_ADMIN_PASSWORD du .env)
Mailpit	http://localhost:8025

Le .env doit porter les cles Airflow avant le premier make dev : AIRFLOW_FERNET_KEY, AIRFLOW_API_SECRET_KEY, AIRFLOW_JWT_SECRET, AIRFLOW_APP_SECRET_KEY et AIRFLOW_ADMIN_PASSWORD. Sans elles airflow-init refuse de demarrer, et airflow-apiserver, airflow-scheduler et airflow-dag-processor avec lui. Il doit aussi porter les six clés GARAGE_* (rpc, jetons, clé S3, clé SSE-C) : make services-up refuse sinon de démarrer Garage, où le DAG retention archive les mesures anciennes (ADR 0019).

Les cibles d'origine restent disponibles pour ne demarrer qu'une partie : make db-up, make airflow-up, make dev-backend, make dev-frontend.

make help liste les cibles disponibles.

Deux fichiers d'environnement, deux usages : .env a la racine alimente docker-compose.yml, apps/backend/.env alimente le backend lance sur le poste. Le port 5433 est publie plutot que 5432, souvent deja pris par une autre base.

Le backend et le frontend tournent sur le poste, lances ensemble par make dev (logs entrelaces dans le meme terminal, Ctrl+C arrete les deux) ; la base, Mailpit et Airflow tournent en conteneur. Le service backend du docker-compose.yml sert la stack complete et la recette, et n'embarque pas le source, donc toute modification y demande un docker compose up -d --build backend.

Donnees de demonstration

Le jeu historique s'arrete au 31/12/2024. make demo-data renseigne les tables que les vues alertes, recommandations et previsions lisent, en ancrant le scoring et la detection a cette date (DEMO_NOW) plutot qu'a l'horloge reelle, qui ne verrait qu'un parc muet depuis des mois. La cible ne fait rien si des alertes existent deja ; make demo-data-force rejoue les trois etapes, toutes idempotentes en base.

Un volume pgdata cree avant db/init/120-airflow-database.sql n'a pas de base airflow : db/init ne rejoue qu'a la premiere initialisation. make db-ensure-airflow, appelee par make dev et make airflow-up, la cree au besoin, sans detruire les donnees applicatives.

Verifier que la base repond et que l'extension est chargee :

curl -s localhost:8000/api/v1/health/ready

Stack complète derrière le reverse proxy

Pour servir l'application comme sur la machine cible, en HTTPS et sous une seule origine. L'overlay emploie !override et !reset, donc Docker Compose 2.24.4 ou plus récent :

make tls-selfsigned PUBLIC_HOST=enervision.local   # certificat de démonstration
make stack-up PUBLIC_HOST=enervision.local         # nginx en 80/443, le reste sur 127.0.0.1

Le navigateur avertit d'un émetteur inconnu : sur le poste, le certificat est auto-signé. Sur la machine, les certificats viennent de Let's Encrypt par défi DNS-01 (ADR 0018). Routage, mode ACME et renouvellement dans infra/proxy/README.md ; la décision et ses motifs dans l'ADR 0007.

Sur la VM ENI, trois environnements cohabitent, production sur main, recette sur dev, et dev pour toute autre branche lancée à la main (ADR 0017), chacun dans son dossier et son projet Compose, derrière un frontal SNI commun : scripts/provision-host.sh les prépare, le workflow deploy.yml les redéploie par un runner auto-hébergé, une fois la CI du commit poussé verte (ADR 0014). Ports, noms d'hôte et garde-fous dans docs/architecture/10-infra.md et l'ADR 0009.

Tests de bout en bout, charge et supervision

Besoin	Commandes	Détail
Parcours utilisateur (Playwright)	make e2e-install, puis make e2e-prepare e2e contre make dev	tests/e2e/README.md
Tir de charge (k6)	make load-smoke, load-test, load-stress, load-limits	tests/load/README.md
Supervision	make monitoring-up, Grafana sur http://localhost:3001	monitoring/README.md

La CI joue les parcours, un tir de fumée et le contrôle de la limitation de débit à chaque PR qui touche l'application, contre la stack de prod derrière le proxy (ADR 0015). La supervision est active en prod, à la demande ailleurs (ADR 0016).

Conventions

• Branches : feat/, fix/, chore/, docs/, test/ suivi d'un libelle court.
• Commits : Conventional Commits, portee = dossier de premier niveau concerne.
• Toute decision structurante donne lieu a un ADR dans docs/adr.
• Toute PR qui change un composant met a jour sa vue dans docs/architecture, dans la meme PR.