# fgaume/affelnet architecture

> Architecture diagram of the GitHub repository fgaume/affelnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fgaume/affelnet
- Repository: https://github.com/fgaume/affelnet

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% CI/CD
  %% =======================
  subgraph "CI/CD (GitHub)"
    Dev["Developer"]:::cicd
    Repo["GitHub Repository"]:::cicd
    GHA_Merge["GitHub Actions: merge deploy"]:::cicd
    GHA_PR["GitHub Actions: PR preview"]:::cicd
    Build["CRA Build (npm run build)"]:::cicd
  end

  Dev -->|"git push/PR"| Repo
  Repo -->|"triggers"| GHA_Merge
  Repo -->|"triggers"| GHA_PR
  GHA_Merge -->|"npm ci"| Build
  GHA_PR -->|"npm ci"| Build

  %% =======================
  %% Cloud (Firebase)
  %% =======================
  subgraph "Firebase (Cloud)"
    Hosting["Firebase Hosting (Static Hosting)"]:::firebase
    StaticHTML["index.html + static assets"]:::firebase
    StaticAPI["Static JSON endpoints (/api/*.json)"]:::firebase
    subgraph "Firestore (BaaS)"
      FirestoreDB[("Cloud Firestore\n(seuils collaboratifs)")]:::db
    end
  end

  Build -->|"firebase deploy"| Hosting
  Hosting -->|"serves"| StaticHTML
  Hosting -->|"serves"| StaticAPI

  %% =======================
  %% External Providers
  %% =======================
  subgraph "External Services (Tiers)"
    ArcGIS["ArcGIS REST APIs (Rectorat Paris / maps.arcgis.com)"]:::external
  end

  %% =======================
  %% Device Boundary
  %% =======================
  subgraph "User Device (Browser)"
    User["Utilisateur (Parent/élève)"]:::user
    Browser["Web Browser"]:::client

    subgraph "PWA React (SPA) — Frontend-only"
      AppShell["App Shell (React entry + composition)"]:::client
      Context["Global State (React Context)"]:::client

      subgraph "Offline & Installability (PWA)"
        SWReg["Service Worker Registration"]:::client
        SW["Service Worker"]:::client
        Manifest["Web App Manifest"]:::client
        SWCache[("Service Worker Cache\n(offline assets/runtime cache)")]:::db
      end

      subgraph "UI Domains (Pages)"
        UI_Bilan["Bilan"]:::ui
        UI_College["Collèges"]:::ui
        UI_Secteurs["Secteurs"]:::ui
        UI_Lycees["Lycées (secteur + filtrage spécialités)"]:::ui
        UI_Seuils["Seuils (contributions)"]:::ui
        UI_Socle["Socle"]:::ui
        UI_Stats["Stats"]:::ui
        UI_Main["Main/Shared UI (Loading/Title)"]:::ui
      end

      subgraph "Shared UI Components"
        Components["Reusable Components\n(AffichageScores, RangeInput, MyToggle, ...)"]:::ui
      end

      subgraph "Client Data Access Layer"
        Services["Services (src/services/*)"]:::service
        S_Local["useLocalStorage (persistence abstraction)"]:::service
        S_Firebase["firebase client init/config"]:::service
        S_Seuils["seuils service (read/write)"]:::service
        S_Secteurs["secteurs service (ArcGIS fetch)"]:::service
        S_Specialites["specialites service (ArcGIS fetch)"]:::service
        S_Lycees["lyceeService (ArcGIS fetch)"]:::service
        S_Bilan["bilan service"]:::service
        S_Socle["socle service"]:::service
        S_Stats["statistiques service"]:::service
        S_Helper["helper utilities"]:::service
      end

      subgraph "Embedded & Static Data"
        DataBundled["Embedded datasets (src/data/*)\n(bundled at build time)"]:::data
      end
    end

    LocalStorage[("Browser LocalStorage\n(user inputs & preferences)")]:::db
  end

  %% =======================
  %% Runtime Flows
  %% =======================
  User -->|"uses"| Browser
  Browser -->|"loads SPA"| AppShell

  %% App loading from Hosting
  Browser -->|"HTTP GET /index.html /static/* /manifest.json"| Hosting
  Hosting -->|"serves static shell"| StaticHTML
  Browser -->|"GET /api/*.json (static)"| StaticAPI

  %% PWA offline
  SWReg -->|"registers"| SW
  SW -->|"cache/fetch"| SWCache
  AppShell -->|"reads manifest"| Manifest
  Browser -->|"install / launch PWA"| Manifest

  %% UI Composition
  AppShell -->|"renders"| UI_Main
  AppShell -->|"routes"| UI_Bilan
  AppShell -->|"routes"| UI_College
  AppShell -->|"routes"| UI_Secteurs
  AppShell -->|"routes"| UI_Lycees
  AppShell -->|"routes"| UI_Seuils
  AppShell -->|"routes"| UI_Socle
  AppShell -->|"routes"| UI_Stats

  UI_Bilan -->|"composes"| Components
  UI_College -->|"composes"| Components
  UI_Secteurs -->|"composes"| Components
  UI_Lycees -->|"composes"| Components
  UI_Seuils -->|"composes"| Components
  UI_Socle -->|"composes"| Components
  UI_Stats -->|"composes"| Components

  %% Global state
  AppShell -->|"provides state"| Context
  UI_Bilan -->|"consume/update"| Context
  UI_College -->|"consume/update"| Context
  UI_Secteurs -->|"consume/update"| Context
  UI_Lycees -->|"consume/update"| Context
  UI_Seuils -->|"consume/update"| Context
  UI_Socle -->|"consume/update"| Context
  UI_Stats -->|"consume/update"| Context

  %% Pages -> Services
  UI_Bilan -->|"calls"| S_Bilan
  UI_College -->|"calls"| Services
  UI_Secteurs -->|"calls"| S_Secteurs
  UI_Lycees -->|"calls"| S_Lycees
  UI_Lycees -->|"calls"| S_Specialites
  UI_Seuils -->|"calls"| S_Seuils
  UI_Socle -->|"calls"| S_Socle
  UI_Stats -->|"calls"| S_Stats

  Services -->|"uses"| S_Helper
  S_Bilan -->|"uses"| S_Local
  S_Socle -->|"uses"| S_Local
  S_Stats -->|"uses"| S_Local
  Services -->|"uses"| S_Local

  %% Local majority data
  S_Local -->|"LocalStorage read/write"| LocalStorage

  %% Embedded datasets
  UI_Bilan -->|"imports"| DataBundled
  Services -->|"imports"| DataBundled

  %% Collaborative thresholds
  S_Seuils -->|"uses"| S_Firebase
  S_Firebase -->|"Firestore SDK"| FirestoreDB
  UI_Seuils -->|"Firestore read/write: seuils"| FirestoreDB

  %% External ArcGIS
  S_Secteurs -->|"ArcGIS REST fetch: secteurs"| ArcGIS
  S_Lycees -->|"ArcGIS REST fetch: lycées secteur"| ArcGIS
  S_Specialites -->|"ArcGIS REST fetch: spécialités"| ArcGIS

  %% =======================
  %% Click events (mapped components)
  %% =======================
  click AppShell "https://github.com/fgaume/affelnet/blob/main/src/App.js"
  click AppShell "https://github.com/fgaume/affelnet/blob/main/src/index.js"
  click AppShell "https://github.com/fgaume/affelnet/blob/main/src/App.css"
  click Context "https://github.com/fgaume/affelnet/blob/main/src/context.js"
  click SW "https://github.com/fgaume/affelnet/blob/main/src/service-worker.js"
  click SWReg "https://github.com/fgaume/affelnet/blob/main/src/serviceWorkerRegistration.js"
  click Manifest "https://github.com/fgaume/affelnet/blob/main/public/manifest.json"
  click StaticHTML "https://github.com/fgaume/affelnet/blob/main/public/index.html"

  click UI_Bilan "https://github.com/fgaume/affelnet/tree/main/src/bilan/"
  click UI_College "https://github.com/fgaume/affelnet/tree/main/src/college/"
  click UI_Lycees "https://github.com/fgaume/affelnet/tree/main/src/lycees/"
  click UI_Secteurs "https://github.com/fgaume/affelnet/tree/main/src/secteurs/"
  click UI_Seuils "https://github.com/fgaume/affelnet/tree/main/src/seuils/"
  click UI_Socle "https://github.com/fgaume/affelnet/tree/main/src/socle/"
  click UI_Stats "https://github.com/fgaume/affelnet/tree/main/src/stats/"
  click Components "https://github.com/fgaume/affelnet/tree/main/src/components/"
  click UI_Main "https://github.com/fgaume/affelnet/tree/main/src/main/"
  click DataBundled "https://github.com/fgaume/affelnet/tree/main/src/data/"

  click Services "https://github.com/fgaume/affelnet/tree/main/src/services/"
  click S_Firebase "https://github.com/fgaume/affelnet/blob/main/src/services/firebase.js"
  click S_Seuils "https://github.com/fgaume/affelnet/blob/main/src/services/seuils.js"
  click S_Local "https://github.com/fgaume/affelnet/blob/main/src/services/useLocalStorage.js"
  click S_Secteurs "https://github.com/fgaume/affelnet/blob/main/src/services/secteurs.js"
  click S_Specialites "https://github.com/fgaume/affelnet/blob/main/src/services/specialites.js"
  click S_Lycees "https://github.com/fgaume/affelnet/blob/main/src/services/lyceeService.js"
  click S_Bilan "https://github.com/fgaume/affelnet/blob/main/src/services/bilan.js"
  click S_Socle "https://github.com/fgaume/affelnet/blob/main/src/services/socle.js"
  click S_Stats "https://github.com/fgaume/affelnet/blob/main/src/services/statistiques.js"
  click S_Helper "https://github.com/fgaume/affelnet/blob/main/src/services/helper.js"

  click Hosting "https://github.com/fgaume/affelnet/blob/main/firebase.json"
  click GHA_Merge "https://github.com/fgaume/affelnet/blob/main/.github/workflows/firebase-hosting-merge.yml"
  click GHA_PR "https://github.com/fgaume/affelnet/blob/main/.github/workflows/firebase-hosting-pull-request.yml"
  click Build "https://github.com/fgaume/affelnet/blob/main/package.json"

  %% =======================
  %% Styles
  %% =======================
  classDef user fill:#E8F1FF,stroke:#2B6CB0,stroke-width:1.5px,color:#0B1F3A
  classDef client fill:#DBEEFF,stroke:#1E5A8A,stroke-width:1.5px,color:#0B1F3A
  classDef ui fill:#CFE8FF,stroke:#1E5A8A,stroke-width:1.2px,color:#0B1F3A
  classDef service fill:#E2F7EE,stroke:#1F7A4D,stroke-width:1.5px,color:#0B2B1B
  classDef data fill:#FFF4CC,stroke:#B7791F,stroke-width:1.5px,color:#3A2206
  classDef db fill:#F2F2F2,stroke:#5A5A5A,stroke-width:1.5px,color:#1A1A1A
  classDef firebase fill:#E6FFFA,stroke:#0F766E,stroke-width:1.7px,color:#062925
  classDef external fill:#FFE3CC,stroke:#C05621,stroke-width:1.7px,color:#3B1406
  classDef cicd fill:#ECEFF4,stroke:#4A5568,stroke-width:1.5px,color:#111827
```
