oc-discovery/docs/diagrams/README.md

OC-Discovery — Diagrammes d'architecture et de séquence

Tous les fichiers sont au format PlantUML. Rendu possible via VS Code (extension PlantUML), IntelliJ, ou plantuml.com/plantuml.

Note : Les diagrammes 06, 07, 12, 14–24 et plusieurs protocoles ci-dessous concernaient l'architecture à 3 niveaux (node → indexer → native indexer), supprimée dans la branche feature/no_native_consortium. Ces fichiers sont conservés à titre historique. Les diagrammes actifs sont indiqués ci-dessous.

Diagrammes actifs (architecture 2 niveaux)

Séquences principales

Fichier	Description
01_node_init.puml	Initialisation d'un Node : libp2p host + PSK + ConnectionGater + ConnectToIndexers + SendHeartbeat + DHT proactive
02_node_claim.puml	Enregistrement du nœud : claimInfo + publishPeerRecord → indexeurs → DHT
03_indexer_heartbeat.puml	Protocole heartbeat bidirectionnel : challenges PeerID + DHT + witness, scoring 7 dimensions, suggestions, SuggestMigrate
04_indexer_publish.puml	Publication d'un PeerRecord vers l'indexeur → DHT (PutValue /node, /name, /pid)
05_indexer_get.puml	Résolution d'un pair : GetPeerRecord → indexeur → DHT si absent local
08_nats_create_resource.puml	Handler NATS CREATE_RESOURCE : propagation partenaires on-demand
09_nats_propagation.puml	Handler NATS PROPALGATION_EVENT : delete, considers, planner, search
10_pubsub_search.puml	Recherche gossip globale (GossipSub /opencloud/search/1.0)
11_stream_search.puml	Recherche directe par stream (type "known" ou "partner")
13_planner_flow.puml	Session planner (ouverture, échange, fermeture)

Résilience et pool management

Fichier	Description
hb_failure_evict.puml	HeartbeatFailure → evictPeer → TriggerConsensus ou DHT replenish
hb_last_indexer.puml	Protection last-indexer → reconnectToSeeds → retryUntilSeedResponds
dht_discovery.puml	Découverte proactive DHT : Provide/FindProviders, SelectByFillRate, dhtCache
connection_gater.puml	ConnectionGater : DB blacklist → DHT sequential check (transport-error fallthrough)

Diagrammes historiques (architecture 3 niveaux — obsolètes)

Ces fichiers documentent l'ancienne architecture. Ils ne correspondent plus au code en production.

Fichier	Description
06_native_registration.puml	Enregistrement d'un indexeur auprès du Native (supprimé)
07_native_get_consensus.puml	ConnectToNatives : fetch pool + Phase 1 + Phase 2 (supprimé)
12_partner_heartbeat.puml	Heartbeat partner permanent (supprimé — connexions on-demand)
14_native_offload_gc.puml	Boucles background Native Indexer (supprimé)
15_archi_config_nominale.puml	Topologie nominale avec natifs (obsolète)
16_archi_config_seed.puml	Mode seed sans natif (obsolète)
17_startup_consensus_phase1_phase2.puml	Démarrage avec consensus natifs (supprimé)
18_startup_seed_discovers_native.puml	Upgrade seed → native (supprimé)
19_failure_indexer_crash.puml	F1 — replenish depuis natif (supprimé)
20_failure_both_indexers_selfdelegate.puml	F2 — IsSelfFallback native (supprimé)
21_failure_native_one_down.puml	F3 — panne 1 natif (supprimé)
22_failure_both_natives.puml	F4 — panne 2 natifs (supprimé)
23_failure_native_plus_indexer.puml	F5 — panne combinée natif + indexeur (supprimé)
24_failure_retry_lost_native.puml	F6 — retryLostNative (supprimé)
25_failure_node_gc.puml	F7 — GC nœud côté indexeur (toujours valide)

Protocoles libp2p actifs

Protocole	Description
/opencloud/heartbeat/1.0	Heartbeat bidirectionnel node→indexeur (long-lived)
/opencloud/probe/1.0	Sonde de bande passante (echo, mesure latence + débit)
/opencloud/witness/1.0	Requête témoin : "quel est ton score de l'indexeur X ?"
/opencloud/record/publish/1.0	Publication PeerRecord vers indexeur
/opencloud/record/get/1.0	Requête GetPeerRecord vers indexeur
/opencloud/resource/search/1.0	Recherche de ressources entre peers
/opencloud/resource/create/1.0	Propagation création ressource → partner
/opencloud/resource/update/1.0	Propagation mise à jour ressource → partner
/opencloud/resource/delete/1.0	Propagation suppression ressource → partner
/opencloud/resource/planner/1.0	Session planner (booking)
/opencloud/resource/verify/1.0	Vérification signature ressource
/opencloud/resource/considers/1.0	Transmission d'un considers d'exécution

Protocoles supprimés (architecture native)

Protocole	Raison
/opencloud/native/subscribe/1.0	Tier native supprimé
/opencloud/native/unsubscribe/1.0	Tier native supprimé
/opencloud/native/indexers/1.0	Remplacé par DHT FindProviders
/opencloud/native/consensus/1.0	Remplacé par TriggerConsensus léger
/opencloud/native/peers/1.0	Tier native supprimé
/opencloud/indexer/natives/1.0	Tier native supprimé
/opencloud/indexer/consensus/1.0	Remplacé par TriggerConsensus
/opencloud/resource/heartbeat/partner/1.0	Heartbeat partner supprimé — on-demand