<!-- file: docs/architecture/ARCHITECTURE.md -->
<!-- version: 2 -->

# 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 alignée fonctionnellement sur le périmètre bot2 `0.4.6`. Les travaux Metaplex Token Metadata partiellement migrés sont repris séparément dans `0.4.7`.