khadhroony-bobobot/ROADMAP.md

<!-- file: ROADMAP.md -->

# khadhroony-bobobot — Roadmap

## 1. Objet du projet

`khadhroony-bobobot` est un workspace Rust destiné à la détection, l’observation, l’analyse de patterns et, à terme, à l’exécution semi-automatisée d’achats/ventes de tokens sur la blockchain Solana.

Le projet vise en priorité :

- la détection de création de tokens et de paires sur différents DEX,
- la réception et le tri des événements on-chain et RPC,
- la collecte de métriques utiles au filtrage,
- l’analyse statistique et comportementale des patterns,
- la préparation d’une couche wallet puis swap/trading.

## 2. Principes d’architecture

### 2.1. Structure générale

Le workspace est organisé autour de deux sous-crates principales :

- `kb_lib` : bibliothèque métier, réseau, config, tracing, stockage, analyse et logique applicative.
- `kb_app` : application Tauri V2 avec frontend TypeScript, chargée de l’interface et de la délégation vers `kb_lib`.

### 2.2. Contraintes de code

Le socle du projet doit respecter les contraintes suivantes :

- Rust 2024.
- Aucun fichier `mod.rs`.
- Exposition centralisée à la racine des crates via `lib.rs` ou `main.rs`.
- Pas d’usage de `anyhow` ni `thiserror`.
- Pas d’usage de `?`, `unwrap`, `expect` dans le code applicatif.
- Utilisation de `match`, `if let Err`, `let Err = ... else`.
- Documentation Rust obligatoire sur les éléments publics.
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` activés et respectés.
- Pas de `use` pour les types/fonctions externes, sauf pour les traits.
- Tests unitaires importants et maintenus à chaque étape.

### 2.3. Règles de responsabilité

- `kb_app` ne doit pas embarquer la logique métier réseau ou Solana.
- `kb_app` doit seulement orchestrer l’UI, les commandes Tauri et les appels vers `kb_lib`.
- `kb_lib` doit porter les clients réseau, la config, le tracing, les types partagés, les registres et la logique métier.

## 3. Vision fonctionnelle

Le projet doit pouvoir évoluer progressivement vers les capacités suivantes :

1. Connexion à plusieurs endpoints HTTP / WS RPC Solana.
2. Répartition des rôles par endpoint.
3. Réception des notifications de slots, comptes, programmes, logs, signatures, blocs.
4. Détection de créations de tokens, pools et paires sur plusieurs DEX.
5. Collecte de métriques : liquidité, market cap, volume, prix, activité.
6. Persistance locale dans SQLite, puis évolution possible vers PostgreSQL.
7. Analyse de patterns et filtrage des tokens non tradables.
8. Gestion de wallets Solana.
9. Préparation puis exécution semi-automatisée de swaps/trading.
10. Intégration future de gRPC Yellowstone.

## 4. Configuration cible

La configuration applicative est stockée dans un fichier `config.json`.

### 4.1. Points à couvrir dans la configuration

Le fichier doit permettre de configurer :

- les endpoints HTTP,
- les endpoints WebSocket,
- un nom logique par endpoint,
- le rôle ou les tâches affectées à chaque endpoint,
- les limites de débit par endpoint,
- les options spécifiques aux providers publics ou privés,
- les chemins de stockage local,
- le répertoire des wallets Solana,
- le tracing et ses formats,
- la stratégie de reconnexion,
- les paramètres de base de données,
- les options d’UI persistées plus tard.

### 4.2. Exemple de catégories attendues

- `app`
- `logging`
- `database`
- `wallets`
- `network`
- `solana`
- `http_endpoints`
- `ws_endpoints`

### 4.3. Exigences particulières

Chaque endpoint doit pouvoir porter sa propre configuration, par exemple :

- nom logique,
- URL,
- provider,
- présence ou non d’une clé API,
- variable d’environnement pour clé API,
- plafond de requêtes,
- burst,
- timeout,
- usages autorisés,
- rôle principal.

Exemples de rôles futurs :

- `slot_notifications`
- `program_subscriptions`
- `account_subscriptions`
- `logs_subscriptions`
- `http_queries`
- `fallback`

## 5. Tracing cible

Le tracing est centralisé dans `kb_lib`.

### 5.1. Exigences initiales

- sortie console paramétrable,
- sortie fichier paramétrable,
- niveau de log configurable,
- format du message configurable,
- format du temps configurable,
- ANSI console activable/désactivable,
- fonctionnement compatible tests,
- séparation claire entre initialisation et usage.

### 5.2. Objectifs complémentaires

- pouvoir distinguer les logs du transport WS,
- distinguer les logs HTTP,
- distinguer les logs Tauri/UI,
- distinguer les logs DB,
- préparer une traçabilité par endpoint et par client.

## 6. Phasage par versions

### 6.1. Version `0.0.2` — Socle conforme
Objectif : corriger le squelette et poser la base de travail.

Réalisé :

- correction de `kb_lib/src/lib.rs`,
- création de `KbError`,
- création de `KbConfig`,
- création de `init_tracing`,
- création des constantes Solana officielles,
- préparation des modules `ws_client` et `http_client`,
- remise de `kb_app/src/lib.rs` en conformité,
- documentation de `kb_app/src/splash.rs`,
- UI Tauri minimale.

### 6.2. Version `0.1.x` — Transport WebSocket générique
Objectif : construire un vrai `WsClient` asynchrone clonable.

Réalisé :

- `connect`, `disconnect`, `connection_state`,
- flux de lecture séparé du flux d’écriture,
- identifiant incrémental interne par client,
- canal sortant borné,
- émission d’événements internes,
- support de l’arrêt propre,
- fermeture avec timeout,
- tests offline avec serveur mock.

### 6.3. Version `0.1.1` — Intégration Tauri minimale du `WsClient`
Objectif : valider le transport via l’application desktop.

Réalisé :

- intégration minimale de `WsClient` dans `kb_app`,
- boutons start/stop,
- zone de logs,
- validation du flux `frontend -> tauri -> kb_lib -> frontend`.

### 6.4. Version `0.2.0` — Couche JSON-RPC WS Solana
Objectif : séparer clairement transport, réponses RPC et notifications.

Réalisé :

- enveloppes JSON-RPC 2.0,
- gestion des `request_id`,
- parsing des réponses et erreurs,
- parsing des notifications,
- premiers helpers JSON-RPC sur `WsClient`.

### 6.5. Version `0.3.0` — Registre subscriptions / notifications
Objectif : fiabiliser la gestion des subscriptions.

Réalisé :

- stockage des subscriptions actives,
- mapping entre requête de subscribe et `subscription_id` serveur,
- unsubscribe propre avant fermeture,
- timeout d’attente sur unsubscribe,
- purge locale si nécessaire,
- routage séparé des notifications.

### 6.6. Version `0.3.1` — Helpers subscribe/unsubscribe WebSocket
Objectif : ajouter les helpers haut niveau correspondant aux principales méthodes PubSub Solana.

Réalisé :

- helpers pour `account`, `block`, `logs`, `program`, `root`, `signature`, `slot`, `slotsUpdates`, `vote`,
- helpers d’unsubscribe correspondants,
- premiers tests de validation des noms de méthodes.

### 6.7. Version `0.3.2` — Helpers typed et notifications typed
Objectif : s’appuyer principalement sur `solana-rpc-client-api` pour typer les subscribe et les notifications.

Réalisé :

- helpers typed pour `account`, `block`, `logs`, `program`, `signature`,
- parsing typed des notifications,
- base de travail pour réduire l’usage direct de `serde_json::Value`.

### 6.8. Version `0.3.3` — Distinction API typed / raw
Objectif : clarifier l’API publique de `WsClient`.

Réalisé :

- suffixe `_raw` sur les helpers raw,
- conservation des helpers typed comme interface plus propre,
- préparation d’une hiérarchie API plus explicite.

### 6.9. Version `0.3.4` — Fenêtre `Demo Ws` dans `kb_app`
Objectif : tester manuellement les souscriptions live dans une fenêtre dédiée.

Réalisé :

- fenêtre séparée `demo_ws`,
- ouverture depuis la fenêtre principale,
- connexion/déconnexion d’un client de démo,
- test de souscriptions live,
- affichage des événements raw et typed,
- premiers tests réels sur `wss://api.mainnet.solana.com`.

### 6.10. Version `0.3.5` — Stabilisation de `Demo Ws`
Objectif : rendre la fenêtre de démonstration robuste sous flux élevé et cohérente avec la configuration.

Réalisé :

- lire correctement les endpoints activés depuis la config et refléter les URLs résolues avec `api_key_env_var`,
- améliorer la sélection réelle des endpoints affichés et utilisables,
- ajouter du throttling / rate limiting de l’affichage UI sous fort débit,
- limiter ou résumer les événements affichés côté fenêtre,
- conserver l’intégralité des traces côté `tracing`,
- éviter le gel de la fenêtre sur `logsSubscribe` et `programSubscribe`,
- conserver des compteurs et états UI exploitables,
- mieux gérer les fermetures/ralentissements d’endpoints publics.

### 6.11. Version `0.4.x` — Transport HTTP générique et helpers RPC

Objectif : construire un `HttpClient` clonable, limité et extensible, puis ajouter les premiers helpers HTTP Solana.

### 6.12. Version `0.4.0` — Socle `HttpClient`
Réalisé :

- client `reqwest` asynchrone clonable,
- résolution d’URL avec support de `api_key_env_var`,
- limiteur local req/sec,
- burst configurable,
- délais configurables,
- profils par endpoint,
- abstraction JSON-RPC HTTP générique,
- premiers appels de validation Solana.

Livrables :

- `HttpClient`,
- enveloppes JSON-RPC HTTP,
- premiers appels :
  - `getHealth`
  - `getVersion`
  - `getSlot`

### 6.13. Version `0.4.1` — Helpers HTTP Solana
Réalisé :

- ajouter des helpers HTTP haut niveau comme pour le client WS,
- distinguer helpers raw et helpers typed quand cela est pertinent,
- couvrir les premières méthodes utiles du RPC HTTP Solana,
- conserver `HttpClient` comme couche générique réutilisable.

### 6.14. Version `0.4.2` — Politique HTTP avancée
Réalisé :

- préparer un état de pause avant envoi pour un endpoint HTTP,
- préparer plusieurs quotas par famille de méthodes,
- distinguer quota RPC général et quota `sendTransaction`,
- préparer un futur pool d’endpoints HTTP et l’arbitrage entre eux.

### 6.15. Version `0.4.3` — Pool d’endpoints HTTP
Réalisé :

- ajouter un pool d’`HttpClient`,
- sélectionner un endpoint selon le rôle demandé,
- ignorer les endpoints `Paused` ou `Disabled`,
- préparer une rotation simple entre endpoints actifs,
- prendre en compte la classe de méthode HTTP,
- préparer le routage multi-RPC et la limitation de concurrence par endpoint.

### 6.16. Version `0.4.4` — Démo HTTP dans `kb_app`
Réalisé :

- ajout d’une fenêtre `Demo Http`,
- ouverture depuis la fenêtre principale,
- exécution manuelle de méthodes HTTP via le pool d’endpoints,
- affichage des réponses JSON-RPC HTTP et des erreurs associées,
- affichage de l’état du pool HTTP et des statuts des endpoints,
- alignement visuel de la fenêtre sur le gabarit `Demo Ws`,
- amélioration des presets UI, copie de réponse et bascule pretty/raw.

### 6.17. Version `0.5.x` — Base de données SQLite
Objectif : poser la persistance locale avec une organisation préparée dès le départ à une future évolution vers PostgreSQL ou un autre backend.

### 6.18. Version `0.5.0` — Socle SQLite
Réalisé :

- configuration DB dans `config.json`,
- ouverture/validation SQLite,
- façade `KbDatabase`,
- premier schéma technique,
- table `kb_db_metadata`,
- séparation `db/entities`, `db/dtos`, `db/queries`, `db/types`.

### 6.19. Version `0.5.1` — Premières tables métier de stockage local
Réalisé :

- ajout des tables de référence pour les endpoints connus HTTP/WS,
- ajout des tables techniques pour les événements runtime locaux,
- mise en place des `entities`, `dtos`, `queries` et `types` associés,
- préparation du stockage local des endpoints HTTP/WS connus et de leur état utile.

### 6.20. Version `0.5.2` — Stockage des tokens observés
Réalisé :

- ajout de la table `kb_observed_tokens`,
- stockage minimal des mints, symboles, noms, statuts et dates d’observation,
- ajout du `token_program`,
- préparation des relations futures avec pools, paires et événements on-chain,
- conservation d’unicité locale par mint sans duplication par endpoint.

### 6.21. Version `0.5.3` — Événements et signaux locaux
Réalisé :

- conservation des événements runtime techniques via `kb_db_runtime_events`,
- ajout des observations on-chain brutes via `kb_onchain_observations`,
- ajout des signaux d’analyse via `kb_analysis_signals`,
- distinction explicite entre événements runtime, observations on-chain et événements métier,
- préparation de la traçabilité de provenance par type de source et endpoint, sans remettre en cause l’unicité locale d’un token par mint.

### 6.22. Version `0.5.4` — Modèle métier normalisé initial
Réalisé :

- ajouter les tables de référence métier pour les DEX, tokens, pools et paires,
- distinguer clairement objets de référence et événements d’activité,
- préparer les relations entre tokens, pools, paires et listings,
- éviter que la détection technique `0.6.x` écrive directement dans des tables trop brutes ou ambiguës.

### 6.23. Version `0.5.5` — Activité métier normalisée
Réalisé :

- ajout des tables de swaps,
- ajout des événements de liquidité,
- ajout des événements de mint et burn utiles au suivi des tokens,
- préparation de l’historique métier nécessaire avant l’arrivée des connecteurs DEX complets.

### 6.24. Version `0.5.6` — Consolidation de la couche stockage
Objectif : stabiliser le schéma avant la détection technique réelle.

À faire :

- conserver l’abstraction du backend dès le départ,
- limiter la dépendance directe au SQL concret aux modules `queries`,
- garder les conversions explicites entre entités DB et DTOs applicatifs,
- durcir les relations, contraintes et index utiles,
- préparer une future compatibilité PostgreSQL sans casser l’organisation générale.

### 6.25. Version `0.6.x` — Détection technique on-chain / RPC
Objectif : commencer la détection utile pour l’application.

À faire :

- réception de notifications ciblées,
- détection de créations de comptes/programmes d’intérêt,
- débuts de normalisation d’événements,
- premiers connecteurs DEX.

### 6.26. Version `0.7.x` — DEX connectors v1
Objectif : structurer les connecteurs par protocole.

Cibles initiales possibles :

- Pump.fun
- PumpSwap
- Raydium
- Meteora
- FluxBeam
- DexLab

À faire :

- identification des programmes,
- décodage des événements utiles,
- création de types métiers propres,
- enrichissement des métadonnées token/pool/pair.

### 6.27. Version `0.8.x` — Analyse et filtrage
Objectif : transformer les événements bruts en signaux exploitables.

À faire :

- agrégation des métriques,
- règles de filtrage,
- exclusions des tokens non tradables,
- statistiques de comportement,
- premiers patterns.

### 6.28. Version `1.x.y` — Wallets et swap préparatoire
Objectif : préparer la couche d’action.

À faire :

- gestion du répertoire wallets,
- chargement sécurisé des keypairs,
- abstraction wallet,
- préparation d’ordres et de swaps,
- simulation et garde-fous.

### 6.29. Version `2.x.y` — Trading semi-automatisé
Objectif : brancher l’analyse à l’action tout en gardant des garde-fous explicites.

À faire :

- scénarios d’achat/vente,
- règles d’entrée/sortie,
- limites de risque,
- confirmations explicites ou semi-automatiques,
- journaux d’exécution.

### 6.30. Version `3.x.y` — Yellowstone gRPC
Objectif : ajouter le connecteur gRPC dédié.

À faire :

- `GrpcClient` basé sur `yellowstone-grpc-client`,
- adaptation du pipeline d’événements,
- coexistence HTTP / WS / gRPC,
- politique de répartition par source.

## 7. Organisation des modules ciblés

### 7.1. `kb_lib`
Modules cibles à court terme :

- `error.rs`
- `config.rs`
- `tracing.rs`
- `constants.rs`
- `types.rs`
- `ws_client.rs`
- `http_client.rs`
- `rpc_json.rs`
- `rpc_ws.rs`
- `rpc_ws_solana.rs`

### 7.2. `kb_app`
Responsabilités cibles :

- lancement Tauri,
- commandes UI,
- affichage des états et messages,
- réception des événements venant de `kb_lib`,
- persistance future des préférences UI,
- fenêtres de démonstration / diagnostic isolées.

## 8. Ligne de conduite sur le `WsClient`
Le `WsClient` doit être conçu en plusieurs couches :

1. transport brut WebSocket,
2. encodage/décodage JSON texte,
3. couche JSON-RPC 2.0,
4. couche Solana subscribe/unsubscribe/notification,
5. couche métier pour la répartition des messages.

Cette séparation évite de mélanger :

- les réponses à requêtes simples,
- les réponses de subscribe,
- les réponses de unsubscribe,
- les notifications push.

## 9. Politique initiale de reconnexion
Au départ :

- pas de reconnexion automatique,
- pas de resubscribe automatique,
- comportement explicite contrôlé par l’appelant.

Plus tard, ce comportement pourra devenir configurable dans `config.json` et pilotable depuis l’application.

## 10. Politique initiale de fermeture
À la fermeture d’un `WsClient` :

1. marquer le client en arrêt,
2. tenter les `unsubscribe` actifs,
3. attendre les réponses dans une fenêtre bornée,
4. forcer la purge locale si nécessaire,
5. fermer proprement le flux d’écriture,
6. laisser se terminer le flux de lecture,
7. journaliser clairement les cas dégradés.

## 11. Documentation et livrables de référence
Le projet doit maintenir au minimum :

- un `README.md` global,
- un `ROADMAP.md` global,
- un `CHANGELOG.md` global,
- des `README.md` et `TODO.md` par crate à mesure de l’évolution,
- des tests unitaires robustes,
- les bindings TS générés via `cargo test export_bindings` lorsque les types partagés évoluent.

## 12. Priorité immédiate
La priorité immédiate est désormais la suivante :

1. démarrer la version `0.5.4` avec le modèle métier normalisé initial,
2. poser les tables de référence pour les DEX, tokens, pools, paires et listings,
3. séparer clairement les objets métier des observations techniques brutes,
4. préparer les relations nécessaires avant la détection technique `0.6.x`,
5. conserver l’abstraction du backend dès cette phase SQLite,
6. reporter la couche analytique agrégée après la fin de `0.6.x`.