# 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 -> ks-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 - `ks-core` fournit les erreurs et identités transversales minimales. - `ks-config` charge, résout et valide les compositions propres aux binaires ainsi que les documents de configuration Solana partagés. - `ks-logging` initialise le logging et le tracing. - `ks-program-ids` centralise les identifiants de programmes et comptes connus. ### 2.2 Noyau métier `ks-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 `ks-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage. ### 2.3 Acquisition et stockage - `ks-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC. - `ks-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 `ks-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 `ks-lib`, des données de `ks-store` et des capacités de `ks-onchain-transport` sans absorber leurs responsabilités. ### 2.5 Démonstrations et applications - `ks-pipeline-demo-scenarios` fournit les fixtures et campagnes réseau réutilisables spécifiques aux validations Devnet/Testnet. Les scénarios réutilisables doivent être appelables sans dépendre du desktop. - Le binaire `ks-pipeline-demo-scenarios-cli` reste un outil ciblé ; son existence n’impose pas d’exposer chaque scénario par un CLI. - `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop. Les commandes et projections UI y restent, tandis que la logique de scénario réutilisable doit être déléguée à `ks-pipeline-demo-scenarios`. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en `0.5.4`. - `ks-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son namespace `ks-*` est stabilisé depuis `0.5.1` et sa restructuration fonctionnelle est planifiée en `0.5.2`. ## 3. Flux principal de données ```text Solana RPC / WebSocket │ v ks-onchain-transport │ v ks-store (données brutes/canoniques) │ v ks-pipeline │ ├── extraction Core ├── sélection des décodeurs ├── décodage via ks-lib ├── matérialisation via ks-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 `ks-program-ids`. - Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `ks-lib`. - Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`. - Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à `ks-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à l’adaptation Tauri, aux payloads UI, à la présentation et à l’appel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`. - Toute primitive ou orchestration réellement généraliste, indépendante de l’UI et d’une campagne de démonstration précise, appartient à `ks-pipeline` ou à la crate métier propriétaire. - 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 La migration bot2 vers bot3 est close pour le périmètre fonctionnel repris jusqu’à `0.4.7`. La version `0.4.8` complète ensuite la fondation Metadata on-chain en distinguant Solana Program Metadata, Token-2022 Token Metadata et Metaplex Token Metadata, avec leurs décodeurs, matérialisateurs, exécuteurs lorsque applicables, orchestration stateful, scénarios réutilisables et intégration desktop. `0.5.1` stabilise le domaine Khadhroony Solana sous `ks-*` / `KS_*` et remplace la configuration monolithique par des documents spécialisés composables, avec une frontière backend/public explicitement sanitisée. La série `0.5.x` ne vise pas à étendre immédiatement la couverture protocolaire : elle migre d’abord les bibliothèques vers `ks-*`, puis stabilise `ks-config`, `ks-wallet`, `ks-store` et les frontières de scénarios afin d’éviter de devoir casser ces fondations après l’arrivée des protocoles trading. `0.6.x` introduira ensuite le décodeur Anchor générique avant la séquence Meteora/Raydium/Pump/Orca/Jupiter.