How fgaume/affelnet works
Type de projet & objectif (à refléter explicitement dans le diagramme)
Projet : application frontend-only React (Create React App) + PWA, déployée en static hosting Firebase Hosting, avec un backend “léger” Firebase/Firestore utilisé uniquement pour une partie des données (les *seuils collaboratifs*).
Le reste (bilan utilisateur, choix, etc.) est stocké côté navigateur (LocalStorage) et/ou embarqué dans le bundle (données src/data/*).
Elle consomme aussi des APIs externes ArcGIS (Rectorat Paris) pour secteurs et spécialités.
Conséquence diagramme : ton architecture n’est pas “frontend + backend monolithique” ; c’est PWA cliente + services externes + Firestore + pipeline CI/CD.
Frontend / PWA
• src/index.js, src/App.js, src/App.css : point d’entrée React / composition haut niveau
• src/service-worker.js, src/serviceWorkerRegistration.js, public/manifest.json : PWA (cache offline, installabilité)
• public/* : assets statiques et index.html (support Firebase Hosting)
Pages / “domains” UI (à dessiner comme sous-systèmes)
• src/bilan/* : écran(s) “bilan” (ex. MonBilan.js, MatiereEditor.js)
• src/college/* : sélection collège (ex. CollegeSelector.js, MesColleges.js)
• src/lycees/* : lycées de secteur + filtrage spécialités
• src/secteurs/* : logique secteurs (ex. Secteurs.js, LyceeSelector.js)
• src/seuils/* : contributions/seuils (UI + édition) — relié à Firestore
• src/socle/* : “Mon Socle”
• src/stats/* : stats, édition stats, etc.
• src/components/* : composants UI réutilisables (toggle, range, affichage scores)
Data & services (cœur “métier” côté client)
• src/data/* : données embarquées (ex. specialites.js, bilan.js)
• src/services/* : couche d’accès données
• firebase.js : init/config Firebase (client)
• lyceeService.js, secteurs.js, specialites.js, socle.js, seuils.js, statistiques.js, bilan.js, helper.js
• useLocalStorage.js : abstraction de persistance LocalStorage
• src/context.js : state global / React Context (point important pour flux de données internes)
Infra / déploiement
• firebase.json : config Hosting / routes / headers / rewrites éventuels
• .github/workflows/firebase-hosting-*.yml : CI/CD (déploiement auto sur Firebase Hosting)
• package.json : CRA scripts (start, build) + dépendances (React, React-Bootstrap, Firebase)
“Main components” à mettre dans le diagramme (niveau container)
Je recommande de produire au minimum un diagramme C4 “Container”, avec ces boîtes :
PWA React (SPA) (bundle JS/CSS + runtime React Hooks)
• sous-composants notables : UI pages (bilan/secteurs/seuils/…)
• State management : context.js
Local Storage (Browser)
• persistance de “toutes les données saisies” sauf seuils (cf README)
Service Worker Cache (PWA)
• cache d’assets + potentiellement cache runtime (selon implémentation CRA)
Firestore (Firebase)
• stockage/lecture/écriture des seuils d’admission collaboratifs
APIs externes ArcGIS (Rectorat / maps.arcgis.com)
• relation collèges ↔ lycées de secteur
• spécialités par lycée
(Optionnel mais utile) Endpoints “API exposées par l’application”
• /api/colleges/*.json, /api/lycees/*.json, /api/secteurs/*.json servis comme fichiers statiques via Hosting (donc pas un backend applicatif)
GitHub + GitHub Actions → Firebase Deploy (pipeline)
• Source: main → workflow → firebase deploy → Hosting
Relations & flux (les flèches indispensables)
Dessine des flèches orientées (et libellées) qui racontent les flux réels :
Chargement de l’app
• Browser → Firebase Hosting : GET /index.html, /static/js/*, /static/css/*, /manifest.json
• PWA ↔ Service Worker Cache : cache/offline (install / fetch)
Données locales (majoritaires)
• PWA → LocalStorage : write/read (bilan, préférences, saisies non-collab)
• ancre ça sur src/services/useLocalStorage.js (ça justifie la boîte “LocalStorage Access Layer” si tu fais un diagramme plus fin)
Données collaboratives (seuils)
• PWA → Firestore : read/write “seuils”
• relie explicitement le module UI src/seuils/* + src/services/seuils.js → src/services/firebase.js → Firestore
Données externes Rectorat (ArcGIS)
• PWA → ArcGIS REST API : fetch secteurs / spécialités
• montre que ces appels servent les écrans lycees/*, secteurs/*, FiltrageSpecialites.js, etc. via src/services/lyceeService.js, src/services/secteurs.js, src/services/specialites.js
Données “référentielles” embarquées / statiques
• PWA (bundle) ← src/data/* : import statique à build time
• Browser → Hosting : GET /api/...json (si utilisé par l’app ou consommé par d’autres)
• précise “static JSON served by Firebase Hosting” (pas de compute)
CI/CD
• Dev → GitHub repo → GitHub Actions → Firebase Hosting (deploy)
• (Optionnel) PR preview workflow (firebase-hosting-pull-request.yml)
Patterns architecturaux à expliciter (pour rendre le diagramme “vrai”)
• SPA/PWA : rendu côté client, navigation logique, service worker/manifest
• Backend-as-a-Service : Firestore comme stockage collaboratif sans serveur applicatif dédié
• Data access layer côté client : src/services/* centralise fetch + logique (bonne séparation UI vs data)
• State global : src/context.js pour partager état/paramètres entre pages
• Offline-first partiel : PWA + données locales ; dépendances réseau pour ArcGIS + Firestore
• Static hosting + JSON endpoints : “API” exposée = fichiers statiques versionnés (année 2021/2022/2023)
Diagramme 1 — Contexte/Container (recommandé comme diagramme principal)
Objectif : comprendre le système en 30 secondes.
• Boîtes : User, Browser, PWA React, LocalStorage, Service Worker Cache, Firebase Hosting, Firestore, ArcGIS APIs, GitHub Actions.
• Flèches : chargement, lecture/écriture local, lecture/écriture Firestore, fetch ArcGIS, pipeline deploy.
Astuce : sépare visuellement “sur l’appareil” vs “cloud” vs “tiers”.
• Colonne gauche : Device (Browser + PWA + LocalStorage + SW Cache)
• Colonne milieu : Firebase (Hosting + Firestore)
• Colonne droite : ArcGIS (external)
• Bande en haut/bas : CI/CD GitHub Actions
Objectif : comprendre le découpage du code et où vivent les responsabilités.
• Grouper en packages (rectangles englobants) :
• pages/domains: bilan, college, lycees, secteurs, seuils, socle, stats
• shared components: src/components/*
• services: src/services/*
• data: src/data/*
• app shell: App.js, index.js, context.js, serviceWorkerRegistration.js
• Flèches :
• pages → services (appel)
• services → (LocalStorage | Firestore | ArcGIS | static JSON)
• pages → components (composition UI)
• App/context → pages (state propagation)
Diagramme 3 — Déploiement (si tu veux être exhaustif)
Objectif : montrer comment le code devient accessible.
• Dev machine → GitHub
• GitHub Actions → build CRA (npm ci, npm run build)
• firebase deploy → Firebase Hosting
• Hosting sert la PWA ; Firestore accessible via SDK client
Liste de composants concrets à ne pas oublier (pour être “très détaillé”)
• PWA shell : App.js, index.js
• Global state : context.js
• Offline/Install : service-worker.js, serviceWorkerRegistration.js, manifest.json
• UI domains : bilan, seuils, secteurs, lycees, college, socle, stats
• Shared UI : AffichageScores, RangeInput, MyToggle
• Data layer : services/* (dont firebase.js, seuils.js, useLocalStorage.js)
• Static datasets : src/data/*
• Hosted static APIs : /api/colleges/*, /api/lycees/*, /api/secteurs/* (servis par Hosting)
• External: ArcGIS endpoints (secteurs, spécialités)
• Infra: Firebase Hosting + Firestore
• CI/CD: GitHub workflows (merge + PR previews)