# CLAUDE.md — Guide de repère pour toute IA intervenant sur ce repo

> À lire en premier, avant toute exploration du code. Ce document décrit la structure
> **réelle et vérifiée** du projet (pas supposée) au 07/08/2026, suite à un audit complet
> (cartographie → réorganisation) mené en 3 phases validées par l'humain.
>
> Voir aussi [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) — document indépendant, maintenu
> séparément, qui fait référence pour les règles de sécurité et la liste des fichiers
> critiques. En cas de divergence entre les deux fichiers sur un point de sécurité,
> **PROJECT_CONTEXT.md prévaut** et il faut demander confirmation à l'humain.

## 0. Contexte métier

Ce dépôt est le socle d'un bot de trading crypto qui **exécute des ordres réels**.
Toute erreur de manipulation a un coût financier direct.

- **Exchange actuellement utilisé dans le code : Binance (spot)**, testnet et production
  séparés (`TESTNET_MODE` dans [config.py](config.py)). Vérifié par les clés
  `BINANCE_API_KEY`/`BINANCE_API_SECRET`, `BINANCE_BASE_URL`, et le package Python
  `binance` installé dans `.venv/`.
- **Migration prévue vers Kraken mi-2026** (fermeture de l'accès Binance en UE) — c'est
  une cible business, **pas encore implémentée dans le code actuel**. Ne pas halluciner
  de code Kraken existant ; si une tâche porte sur cette migration, elle démarre de zéro
  sur la base de l'architecture Binance décrite ici.
- Un second déploiement, `crypto_trading_prod/` (hors de ce repo), a été créé en vue d'un
  passage en réel puis **arrêté suite à des résultats catastrophiques en test**. Il est
  **hors périmètre** de toute intervention sur `crypto_trading_bot/` — ne pas le
  documenter ni le réorganiser en même temps. Vérifier manuellement côté serveur qu'aucun
  process n'y tourne avant toute action le concernant.

## 1. Processus actifs en production (vérifiés par PID, pas par supposition)

| Process | Fichier | Rôle |
|---|---|---|
| `trading_bot.py` | racine | Bot principal — exécute les ordres réels, gère les positions ouvertes |
| `market_spy.py` | racine | Détection de surges/entrées, place des ordres (testnet). Une copie distincte tourne dans `crypto_trading_prod/` (hors périmètre) |
| `dashboard_api_server.py` | racine | API + sert `dashboard.html`/`mobile.html`. Relancé automatiquement toutes les 5 min par le cron `watchdog_dashboard.sh` (chemin absolu — **ne jamais déplacer ce fichier sans mettre à jour le cron dans le même commit**) |
| `bot_watchdog.py` | racine | Surveille `trading_bot.py` via `bot.pid`, le relance si mort |
| `auto_updater_service.py` | racine (`--daemon`) | Alimente en continu `historical_data/` et déclenche le ré-entraînement LSTM (`train_ai_model.py` via `ai_adaptive_retrainer.py`) |

⚠️ Aucun systemd/pm2/tmux/screen ne supervise ces 5 process (à part le cron du dashboard).
Un redémarrage serveur nécessite un relancement manuel — vérifier avec l'humain avant
toute intervention qui affecterait leur disponibilité.

## 2. Architecture réelle — chaîne de décision

```
config.py (clés API + paramètres risque)
   │
   ├─► trading_bot.py ──► market_safety.py (garde-fous)
   │        │            ├─► pattern_manager.py
   │        │            ├─► trade_logger.py (journal des trades)
   │        │            └─► ai_predictor.py (lazy import, sell timing)
   │        │                     │
   │        │                     └─► chaîne IA/scoring (voir §4)
   │
   └─► market_spy.py ──► market_behavior.py (régime + blacklist dynamique)
            │            ├─► market_context.py
            │            ├─► execution_logger.py (slippage/fills réels)
            │            ├─► signal_aggregator.py / signals_consumer.py
            │            └─► lit framework_tracking.json (écrit par
                              ai_opportunity_selector.py, process séparé,
                              ne trade pas lui-même)

dashboard_api_server.py ──► api/ (routes.py, services.py, security.py, models.py, utils.py)
      │                          │
      │                          └─► lance en subprocess (boutons du dashboard) :
      │                              ai_optimizer.py, analyze_trade_logs.py,
      │                              spy_exit_analyzer.py, spy_param_patcher.py
      └─► ai_realtime_service.py, crypto_data_fetcher.py, ai_predictor.py
```

## 3. Rôle des dossiers principaux

| Dossier | Rôle | Statut |
|---|---|---|
| [api/](api) | Backend du dashboard (routes, sécurité `.api_token`, services) | **Actif** |
| [tests/](tests) | Tests unitaires de `api/` | Actif, légitime |
| [data/](data) | État live du régime marché (`spy_regime_state.json`) | Actif |
| [exec_logs/](exec_logs) | Logs d'exécution réels mensuels (fills, slippage) | **Actif — source de vérité, ne jamais supprimer** |
| [trade_logs/](trade_logs) | Historique des trades/signaux | **Actif — ne jamais supprimer** |
| [models/](models) | Modèles ML chargés en production (`.pt`) | Actif |
| [trained_models/](trained_models) | État du ré-entraînement adaptatif | Actif |
| [historical_data/](historical_data) | Klines historiques par symbole, alimenté par `auto_updater_service.py` | Actif |
| [crypto_cache/](crypto_cache) | Cache utilisé par `crypto_data_fetcher.py`/`trading_bot.py` | Actif |
| [backtest_cache/](backtest_cache) | Cache klines pour les endpoints backtest du dashboard | Actif (référencé par `dashboard_api_server.py`) |
| [logs/](logs) | Logs actifs (rotation via `/etc/logrotate.d/crypto-bot`, config système hors repo) | Actif |
| [spy_optimizer/](spy_optimizer) | Sous-projet GPU séparé (entraînement modèles), 2.7 Go | Actif mais **hors périmètre** des audits de structure — traiter séparément |
| [scripts_debug/](scripts_debug) | Scripts ponctuels non référencés ailleurs, classés par usage : `checks/`, `analyzers/`, `backtests/`, `diagnostics/`, `maintenance_manuelle/`, `monitoring_ponctuel/` | Inerte — utilitaires manuels, jamais appelés automatiquement |
| [docs_archive/](docs_archive) | Rapports/analyses historiques non référencés, classés : `analyses/`, `fixes/`, `guides/`, `rapports/` | Inerte — historique de développement |
| [legacy/](legacy) | `freqai_experiment/` (cluster FreqAI isolé, jamais connecté au bot live), `outils_ponctuels/` (scripts manuels non référencés), `test_optimisation/` (ancien espace d'audit exécution/watchlist) | Inerte |
| [archive_legacy/](archive_legacy) | Copie figée d'une ancienne version du projet (13 fichiers), non utilisée | Inerte |
| [legacy_windows_scripts/](legacy_windows_scripts) | `.bat`/`.ps1`/`.vbs` d'un ancien poste de dev Windows — **non exécutables sur ce serveur Linux** (aucun PowerShell installé) | Inerte |
| [backups_archive/](backups_archive), [logs_archive/](logs_archive), [debug_output_archive/](debug_output_archive), [data_archive_ponctuelle/](data_archive_ponctuelle) | Snapshots/backups/logs rotés archivés lors du nettoyage du 07/08/2026 | Inerte |

## 4. Chaîne IA/scoring (tous importés directement par `ai_predictor.py`, donc actifs)

`ai_advanced_scorer.py`, `ai_compatibility_scorer.py`, `ai_sell_predictor.py`,
`advanced_feature_engineering.py`, `advanced_strategies.py`, `correlation_analyzer.py`,
`ensemble_ml.py`, `ensemble_predictor.py`, `feature_engineering.py`,
`long_term_trend_analyzer.py`, `lstm_reversal_predictor.py`, `monte_carlo_simulator.py`,
`multi_timeframe_analyzer.py`, `outlier_detection.py`, `performance_analyzer.py`,
`risk_adjusted_scorer.py`, `smart_entry_criteria.py`, `smart_rotation.py`,
`technical_analyzer.py`, `time_pattern_analyzer.py`, `volatility_scorer.py`,
`volume_profile_analyzer.py`, `market_context.py`, `market_regime_detector.py`.

`ai_optimizer.py` + ses dépendances (`ai_optimized_config.py`, `optimized_config.py`) et
`ai_self_optimizer.py`, `ai_realtime_service.py`, `train_ai_model.py` (lancé en
subprocess par `ai_adaptive_retrainer.py`) sont également actifs, appelés depuis le
dashboard ou l'auto-updater.

`ai_opportunity_selector.py` : process séparé, n'importe rien du bot, écrit
`framework_tracking.json` que `market_spy.py` lit en fichier (pas en import).

## 5. Conventions de nommage observées

- `ai_*.py` — modules de la chaîne prédiction/scoring IA.
- `market_*.py`, `spy_*.py` — logique de marché et de surveillance (`market_spy.py`).
- `check_*.py`, `_check_*.py` — scripts de vérification ponctuelle manuelle → `scripts_debug/checks/`.
- `analyze_*.py`, `analyse_*.py` — scripts d'analyse ponctuelle → `scripts_debug/analyzers/`.
- `backtest_*.py`, `crashtest_*.py` — scripts de backtest ponctuel → `scripts_debug/backtests/`.
- `diagnose_*.py`, `diagnostic_*.py` — scripts de diagnostic ponctuel → `scripts_debug/diagnostics/`.
- Préfixe `_` (`_verify_integration.py`, `_seed_coin_scores.py`...) — scripts internes
  ponctuels écrits pour un besoin précis et daté, jamais destinés à être importés.
- `*.pid` — fichier de PID d'un process (actif ou non — **vérifier le process réel avant
  de considérer un `.pid` comme obsolète**, certains sont lus par `api/routes.py`/
  `Reset_trading.py` même quand le PID est périmé).
- `*.bak`, `*.bak_YYYYMMDD_HHMMSS`, `*.backup_YYYYMMDD_HHMMSS` — anciennes sauvegardes
  ponctuelles → `backups_archive/`.
- `*_archive/`, `*_ponctuel(le)/`, `legacy*` — dossiers d'archivage créés lors de l'audit
  du 07/08/2026, contenu inerte par construction.
- `START_*.bat/.ps1/.vbs`, `STOP_*.bat`, `RESTART_*.bat` — lanceurs hérités d'un ancien
  poste de développement Windows, non exécutables sur ce serveur Linux.

## 6. 🔒 Fichiers à NE JAMAIS modifier/déplacer/renommer sans validation humaine explicite

**Cœur trading (process actifs ou appelés en subprocess par un process actif) :**
`trading_bot.py`, `market_spy.py`, `dashboard_api_server.py`, `bot_watchdog.py`,
`auto_updater_service.py`, `config.py`, `market_safety.py`, `market_behavior.py`,
`market_regime.py`, `market_regime_detector.py`, `market_context.py`, `dynamic_sltp.py`,
`pattern_manager.py`, `smart_entry_criteria.py`, `smart_rotation.py`,
`execution_logger.py`, `signal_aggregator.py`, `signals_consumer.py`, `trade_logger.py`,
`performance_analyzer.py`, `ai_predictor.py` et toute la chaîne IA du §4,
`ai_optimizer.py`, `ai_optimized_config.py`, `optimized_config.py`, `ai_self_optimizer.py`,
`ai_realtime_service.py`, `train_ai_model.py`, `ai_adaptive_retrainer.py`,
`analyze_trade_logs.py`, `spy_exit_analyzer.py`, `spy_param_patcher.py`, dossier `api/`
entier.

**Scripts manuels destructifs** (jamais exécutés automatiquement par une IA, jamais sans
confirmation explicite de l'humain) : `sell_all.py` (vend toutes les positions),
`Reset_trading.py` (reset complet de l'état de trading).

**Gestion des clés / auth** : `config.py`, `.api_token`, `.dashboard_auth`,
`.freeze_reset_time`.

**Données live de position/état** (ne jamais écraser, ne jamais recopier leur contenu
réel dans un fichier versionné) : `positions.json`, `positions_backup*.json`,
`watchlist.json`, `bot_settings.json`, `trading_profiles.json`, `trading_pause.json`,
`bot.pid`, `market_spy.pid`, `signal_aggregator.pid`, `spy_prod.pid`, `spy_testnet.pid`,
`watchdog.pid`, `auto_updater.pid`, `bot.disabled`.

**Infrastructure liée par un chemin absolu externe** : `watchdog_dashboard.sh` (cron,
relance `dashboard_api_server.py` toutes les 5 min — si `dashboard_api_server.py` devait
un jour être déplacé, ce script doit être mis à jour **dans le même commit**).

## 7. Pièges connus du repo

- **`legacy/outils_ponctuels/cleanup_obsolete_files.py`** contient une liste
  `OBSOLETE_FILES` **périmée** qui cite à tort des fichiers aujourd'hui actifs
  (`config.py`, `trading_bot.py`, `market_regime_detector.py`...) comme obsolètes. Ne
  jamais s'y fier ni l'exécuter tel quel.
- Une "Certain/référencé" détectée par simple recherche texte ne veut pas dire "vivant" :
  beaucoup de références historiques pointent vers des `.md` aujourd'hui archivés dans
  `docs_archive/`. Le seul critère fiable de vivacité est la chaîne d'import réelle
  depuis un des 5 process actifs du §1 (vérifiée ligne par ligne lors de l'audit du
  07/08/2026, pas déduite).
- `crypto_trading_prod/` (hors de ce repo) : déploiement legacy arrêté, hors périmètre,
  audit séparé nécessaire s'il est un jour réactivé.
- `spy_optimizer/` : sous-système actif mais volontairement non audité avec le reste —
  traiter dans un audit dédié si nécessaire.

## 8. Méthodologie attendue de toute IA travaillant sur ce repo

1. Lire ce fichier et [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) en premier.
2. Cartographier/vérifier par recherche de référence avant toute proposition de
   changement — ne jamais supposer un rôle à partir du seul nom de fichier.
3. Aucune modification sur un fichier du §6 sans confirmation humaine explicite, même en
   mode agent autonome.
4. Archiver plutôt que supprimer (déplacement vers un dossier dédié, jamais de
   suppression directe sans période d'observation).
5. La vérification cron/systemd/process actifs côté serveur reste à la charge de
   l'utilisateur — un outil IA depuis l'éditeur n'y a pas toujours accès complet.