110 lines
5.0 KiB
Markdown
110 lines
5.0 KiB
Markdown
<!-- file: docs/architecture/ARCHITECTURE.md -->
|
||
<!-- version: 4 -->
|
||
|
||
# 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 les fixtures et les campagnes automatisées spécifiques à Devnet/Testnet. Ces campagnes peuvent reproduire en parallèle les parcours de démonstration du desktop afin de les valider par des tests sans déplacer les scénarios UI hors de `kb-app-demo-desktop`.
|
||
- Le binaire `kb-pipeline-demo-scenarios-cli` a été introduit pour préparer les fixtures SPL Token-2022 utilisées ensuite par les démonstrations d’exécution Devnet ; il ne constitue pas, par défaut, une interface générale de tous les scénarios.
|
||
- `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 UI spécifiques à Devnet/Testnet restent dans `kb-app-demo-desktop`. Lorsqu’un même parcours doit être validé automatiquement, un scénario équivalent est ajouté en parallèle dans les tests de `kb-pipeline-demo-scenarios` ; cette duplication contrôlée de parcours de validation ne déplace pas le scénario UI.
|
||
- Toute primitive ou orchestration réellement généraliste, indépendante de l’UI et d’une campagne de démonstration précise, appartient à `kb-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
|
||
|
||
L’architecture bot3 est alignée fonctionnellement sur le périmètre bot2 `0.4.6`. Tout le travail Metaplex Token Metadata réalisé dans bot2 a été migré dans bot3 ; `0.4.7` achève cette surface à partir de cette base migrée complète.
|