Créer la page Architecture du wiki

Architecture.md

@@ -0,0 +1,50 @@
+# Architecture
+
+## Vue d'ensemble
+
+`pronote-sync` est un pipeline qui synchronise les données de **Pronote** vers **CalDAV** (agendas) et **XMPP** (notifications). Le flux principal est : **Pronote (iCal/pronotepy) → normalisation → comparaison avec l'agenda théorique → synchronisation CalDAV → synthèse IA (optionnelle) → notification XMPP**. Les sources sont **iCal** (primaire) et `pronotepy` (repli), avec trois modes de source : `auto`, `ical` et `pronotepy`.
+
+## Pipeline
+
+1. Récupération Pronote (iCal + pronotepy) — agenda, devoirs, messages
+1. Normalisation et parsing — parsing iCal → modèles Pydantic, déduplication, normalisation des UID
+1. Récupération du blog (RSS) — `feedparser`, déduplication par GUID, cache HTTP
+1. Comparaison avec l'agenda théorique — matching déterministe, détection des changements
+1. Synchronisation CalDAV — sync différentielle et idempotente, UID stables, conservation des annulés
+1. Synthèse IA (optionnelle) — synthèse des changements, mode dégradé si échec
+1. Envoi XMPP — message structuré (synthèse + devoirs bruts)
+
+## Modules
+
+```
+pronote_sync/
+├── config/          Configuration (Pydantic Settings)
+├── models/          Modèles de données (Pydantic v2)
+├── sources/         Connecteurs (Pronote iCal/pronotepy, blog RSS, agenda théorique)
+├── sync/            Synchronisation CalDAV et comparaison
+├── synthesis/       Synthèse IA (OpenAI, litellm, openai-compatible)
+├── channels/        Canaux de sortie (XMPP)
+├── pipeline/        Orchestration (composition root, PipelineRunner)
+├── utils/           Utilitaires (redaction, logging, UID)
+└── cli/             Interface en ligne de commande
+```
+
+## Injection de dépendances
+
+Le projet utilise `typing.Protocol` et une **composition root** dans `pipeline/run.py`. Aucun singleton global n'est autorisé. Le `PipelineRunner` reçoit toutes ses dépendances via **injection par constructeur** : `PronoteFetcher`, `CalDAVClient`, `AgendaComparator`, `SynthesisProvider`, `Channel`.
+
+## Sources de données
+
+Les modes de source sont les suivants :
+
+- `auto` : essaie d'abord iCal, puis bascule vers `pronotepy` **uniquement** si iCal lève une exception.
+- `ical` : utilise **uniquement** iCal, sans bascule silencieuse.
+- `pronotepy` : utilise **uniquement** `pronotepy`, sans bascule silencieuse.
+- En mode `auto`, si iCal **et** `pronotepy` échouent → erreur critique explicite.
+- Une liste vide est un **succès valide**, pas une panne.
+- `PRONOTE_URL` (connexion API) et `PRONOTE_ICAL_URL` (flux iCal) sont deux paramètres **distincts**.
+- Les messages ne sont disponibles que via `pronotepy` (absents du flux iCal).
+
+## Flux de données
+
+Le flux de données suit ce chemin : données brutes (iCal/`pronotepy`) → modèles Pydantic (`Lesson`, `Homework`, `Message`, etc.) → `PronoteData` (agrégé) → `AgendaDiff` (comparaison) → `CalDavSyncResult` → `SynthesisInput`/`SynthesisResult` → `XmppMessage` → envoi via le canal XMPP.