v0.1.0-pre.067

2026-07-31 07:38:27 +02:00
parent 06fddf63b3
commit 5382cf8f43
11 changed files with 505 additions and 193 deletions
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -0,0 +1,107 @@
+<!-- file: docs/architecture/ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture générale
+
+## 1. Vue d’ensemble
+
+Le workspace est organisé en couches orientées responsabilités :
+
+```text
+configuration ─────┐
+logging ───────────┼──────────────┐
+program IDs ───────┘              │
+                                  v
+transport -> store -> pipeline -> kb-lib
+                         │          │
+                         v          v
+                 demo scenarios   wallet/signers
+                         │          │
+                         └────┬─────┘
+                              v
+                    desktop demo application
+```
+
+Cette représentation indique les relations dominantes. Elle ne remplace pas le graphe exact des dépendances Cargo.
+
+## 2. Couches
+
+### 2.1 Fondations
+
+- `kb-core` fournit les erreurs et identités transversales minimales.
+- `kb-config` charge, résout et valide la configuration.
+- `kb-logging` initialise le logging et le tracing.
+- `kb-program-ids` centralise les identifiants de programmes et comptes connus.
+
+### 2.2 Noyau métier
+
+`kb-lib` contient quatre familles principales :
+
+- modèles et contrats partagés ;
+- décodeurs ;
+- exécuteurs ;
+- matérialisateurs.
+
+La façade publique est constituée par les réexports de `kb-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage.
+
+### 2.3 Acquisition et stockage
+
+- `kb-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC.
+- `kb-store` regroupe les contrats store-neutral et l’implémentation PostgreSQL.
+
+Les transports n’effectuent pas la matérialisation métier. Le stockage ne décide pas quelle surface protocolaire doit être décodée.
+
+### 2.4 Orchestration
+
+`kb-pipeline` orchestre :
+
+- backfill ;
+- extraction Core ;
+- replay de décodage ;
+- matérialisation ;
+- corrélation stateful ;
+- préflight et orchestration d’exécution pour les surfaces prises en charge.
+
+Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacités de `kb-onchain-transport` sans absorber leurs responsabilités.
+
+### 2.5 Démonstrations et applications
+
+- `kb-pipeline-demo-scenarios` fournit une bibliothèque réutilisable et le binaire `kb-pipeline-demo-scenarios-cli`.
+- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop.
+- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son périmètre reste incomplet.
+
+## 3. Flux principal de données
+
+```text
+Solana RPC / WebSocket
+        │
+        v
+kb-onchain-transport
+        │
+        v
+kb-store (données brutes/canoniques)
+        │
+        v
+kb-pipeline
+        │
+        ├── extraction Core
+        ├── sélection des décodeurs
+        ├── décodage via kb-lib
+        ├── matérialisation via kb-lib
+        └── stockage des résultats
+```
+
+L’exécution suit un flux séparé : intention typée, construction, préflight, simulation, confirmation opérateur, envoi, confirmation et validation postérieure lorsque la surface le permet.
+
+## 4. Frontières obligatoires
+
+- Les IDs canoniques ne doivent pas être dispersés lorsqu’ils appartiennent au registre de `kb-program-ids`.
+- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `kb-lib`.
+- Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`.
+- Les scénarios réutilisables doivent migrer vers `kb-pipeline-demo-scenarios` plutôt que rester enfouis dans l’UI.
+- Les fixtures contractuelles communes restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont consommées par plusieurs tests.
+- Les archives documentaires ne participent ni au build ni aux décisions normatives.
+
+## 5. État de migration
+
+L’architecture bot3 est largement alignée fonctionnellement sur le périmètre bot2 proche de `0.4.6`, avec des travaux `0.4.7` partiellement migrés. L’alignement officiel de version reste conditionné à l’audit ciblé prévu par `docs/V0_4_6_ALIGNMENT_AUDIT.md`.