khadhroony-solana-project/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md

<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
<!-- version: 7 -->

# Couches et dépendances KSP

## Rôle des niveaux architecturaux

Les niveaux architecturaux N1–N4 décrivent les familles de composants du projet. Ils ne doivent pas être confondus avec les niveaux durables D1–D4.

### N1 — Fondations communes

- `ksp-core-lib` ;
- `ksp-logging-lib` ;
- `ksp-config-lib` ;
- premières règles/outils transversaux.

### N2 — Capacités Solana réutilisables

- `ksp-onchain-transport-lib` ;
- `ksp-offchain-transport-lib` ;
- `ksp-wallet-lib` ;
- `ksp-interface-lib` ;
- `ksp-program-api` puis implementations Program ;
- `ksp-execution-policy-api` et orchestration d'exécution lorsqu'un vertical slice réel le justifie.

### N3 — Données, jobs, workers et processing

- `ksp-store-api` / `ksp-store-lib` ;
- `ksp-materializer-api` / implementations lorsque DECODE s'ouvre ;
- `ksp-job-api` et jobs ;
- `ksp-worker-api` et workers ;
- processors/pipelines spécialisés réellement réutilisés.

### N4 — Exécutables

- applications desk ;
- services workers ;
- outils/jobs exécutables ;
- demos/scenarios ;
- future orchestration globale.

## Chaîne durable indépendante des niveaux N1–N4

La chaîne de données canonique est :

```text
D1 RAW
  -> D2 CORE
  -> D3 DECODE
  -> D4 SPECIALIZED
```

Aliases fonctionnels :

```text
RAW -> CORE -> DECODE -> SPECIALIZED
```

RAW et CORE sont indépendants du décodage Program.

CORE est une normalisation générique de Solana : structure des blocs, transactions, messages, comptes, instructions/CPI brutes, logs/meta et relations fondamentales.

Le premier decoder Program intervient seulement à `CORE -> DECODE`.

## Progression par couche

### RAW et CORE

Ces deux couches sont construites horizontalement.

À la fin de chaque couche, KSP ajoute les composants d'exploitation nécessaires : persistence, replay/backfill, worker/service et application de contrôle lorsque utiles.

### DECODE et SPECIALIZED

À partir du décodage, KSP progresse verticalement par groupe fonctionnel :

```text
wire
 -> decode
 -> materialize
 -> specialized projection si utile
 -> execution preparation
 -> policy
 -> execute
 -> scenarios
```

Cela évite de développer tous les decoders avant les matérialisations et toutes les executions.

## Séparation maximale des dépendances

Chaque composant possède son contrat et reçoit explicitement les données nécessaires.

Exemples structurants :

```text
ksp-onchain-transport-lib -X-> ksp-config-lib
ksp-onchain-transport-lib -X-> ksp-store-api
ksp-wallet-lib            -X-> ksp-onchain-transport-lib
ksp-wallet-lib            -X-> execution policy
ksp-interface-lib         -X-> ksp-program-api
ksp-execution-lib         -X-> ksp-program-lib
```

La composition supérieure relie les composants.

## Configuration

`ksp-config-lib` est l'unique propriétaire des documents Config, `.env` et variables KSP/KSPB.

Un composant ne dépend pas de Config pour être utilisable. Il expose des settings publics.

Config peut fournir un document standard et un adapter vers ces settings lorsque cela devient utile :

```text
ksp-config-lib -> public settings du composant
```

sans dépendance inverse.

## Logging

`ksp-logging-lib` reste l'unique façade KSP de tracing runtime.

Les crates comportant du comportement runtime peuvent en dépendre. Les crates `*-api` purement déclaratives n'ajoutent cette dépendance que si elles ont réellement un comportement à logger.

## Applications

Les applications Tauri restent minces :

- DTOs applicatifs ;
- composition de services KSP ;
- lifecycle fenêtre/UI ;
- instrumentation frontend ;
- aucun déplacement de logique de transport, Wallet, Config, Program, Store ou Materializer dans Tauri.

Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, backfill/RAW tooling, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites.

## Workers et jobs

Un worker est un service continu/autonome ; un job est borné/terminable.

Ils utilisent des APIs lifecycle distinctes et ne s'appellent pas entre eux pour transférer les payloads du data plane.

Le Store reste le point durable de synchronisation entre couches de processing.

## Firewall des dépendances externes

Les exécutables et couches supérieures n'importent pas directement les crates Solana/protocoles métier lorsqu'une façade KSP existe ou est prévue.

Exceptions bas niveau explicitement autorisées restent limitées aux primitives stables décidées par les règles KSP.

`ksp-interface-lib` concentre les interfaces/wires officielles ou compatibles afin d'éviter les doublons de générations et les dépendances protocolaires dans les couches supérieures.

## Principe contract-first

Une crate `*-api` est créée uniquement lorsque l'extension externe/backend/lifecycle exige un contrat séparé.

Cas décidés :

```text
ksp-program-api
ksp-materializer-api
ksp-store-api
ksp-worker-api
ksp-job-api
ksp-execution-policy-api
```

`ksp-interface-lib`, Wallet et transports conservent pour l'instant leurs APIs publiques dans leur bibliothèque d'implémentation.

## Groupes Program prioritaires

Après RAW/CORE :

```text
Solana Core Programs
-> SPL token/trading
-> token metadata
-> Anchor
-> Meteora
-> Raydium
-> Pump
-> Orca
-> Market Desk V1
-> Jupiter/OKX routing
-> Market Desk V2
-> trading-adjacent
-> general decoding
```

Un satellite nécessaire à un protocole reste dans son groupe : Pump fee avec Pump, Meteora vault avec Meteora, etc.

## Questions encore ouvertes

- forme exacte des settings publics Transport ;
- nécessité future d'un pool automatique de sessions WebSocket ;
- split éventuel d'une API Interface séparée uniquement si un vrai besoin apparaît ;
- contrats Rust exacts de Program/Materializer/Store ;
- mécanisme IPC du premier manager de worker autonome ;
- granularité future des workers DECODE/SPECIALIZED par groupe.