# CLAUDE.md — Trading AI Secure

## Projet
Système de trading algorithmique avec IA adaptative.
- **Langage** : Python 3.11
- **Dépôt** : `/home/tika/trading-project/`
- **Stack Docker** : `docker-compose.yml` à la racine du projet

## Architecture des containers
| Container | Port | Rôle |
|---|---|---|
| `trading-api` | 8100 | FastAPI — orchestration, risk, backtest |
| `trading-ml` | 8200 | Microservice ML (XGBoost, LightGBM, HMM, Optuna) |
| `trading-dashboard` | 8501 | Streamlit UI |
| `trading-jupyter` | 8888 | JupyterLab |
| `trading-grafana` | 3100 | Dashboards Prometheus |
| `trading-db` | — | TimescaleDB (PostgreSQL + time-series) |
| `trading-redis` | — | Cache (données marché, signaux) |

NPM (port 80/443) reverse-proxy vers ces services depuis `/docker/docker-compose.yml`.

## Conventions à respecter
- **Langue des commentaires et logs** : Français
- **Stop-loss** : OBLIGATOIRE sur chaque trade — jamais de position sans SL
- **RiskManager** : Singleton strict — ne jamais instancier deux fois
- **Circuit breakers** : NE JAMAIS désactiver en production
- **Paper trading** : minimum 30 jours avant activation du live trading
- **Seuils de validation** : Sharpe ≥ 1.5, Max Drawdown ≤ 10%, Win Rate ≥ 55%

## Fichiers critiques
```
src/utils/config_loader.py   # Charge YAML + ${ENV_VAR} + overrides Docker
src/core/risk_manager.py     # Singleton VaR/CVaR/circuit breakers/Telegram
src/core/notifications.py    # TelegramNotifier + EmailNotifier
src/db/models.py             # Trade, OHLCVData, BacktestResult, MLModelMeta
src/db/session.py            # SQLAlchemy engine, get_db(), init_db()
src/api/app.py               # FastAPI lifespan (init DB + RiskManager)
src/api/routers/trading.py   # Routes wirées au business logic
src/ml/service.py            # Microservice ML FastAPI
```

## Configuration
Copier `.env.example` → `.env` et renseigner :
- `TRADING_DB_PASSWORD` : mot de passe TimescaleDB
- `GRAFANA_ADMIN_PASSWORD` : mot de passe Grafana
- `ALPHA_VANTAGE_API_KEY` : clé API gratuite (500 calls/jour)
- `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID` : alertes temps réel

Le `ConfigLoader` supporte `${VAR_NAME}` et `${VAR_NAME:-default}` dans les YAML.
Il override automatiquement `data_sources.cache.redis` depuis `REDIS_URL`.

## Commandes
```bash
make docker-init        # Premier démarrage (crée .env + build + up)
make docker-up          # Démarrer tous les services
make docker-down        # Arrêter
make docker-logs        # Logs de tous les services
make docker-api-logs    # Logs API uniquement
make docker-build       # Rebuild les images
```

## Phases de développement
| Phase | Statut | Description |
|---|---|---|
| Phase 1 : Architecture | 🟡 En cours | FastAPI, DataService, RiskManager, Docker |
| Phase 2 : IA Adaptative | ⚪ Planifié | MLEngine, RegimeDetector, Optuna, Kelly |
| Phase 3 : Stratégies | ⚪ Planifié | Backtesting, walk-forward, Monte Carlo |
| Phase 4 : Interface | ⚪ Planifié | Dashboard connecté à l'API, alertes UI |
| Phase 5 : IG Markets | ⚪ Planifié | Broker réel après 30j paper trading validé |

## Avancement actuel (Phase 1)
### Terminé
- Infrastructure Docker 8 services
- ConfigLoader avec substitution env vars
- Modèles SQLAlchemy (Trade, OHLCVData, BacktestResult, MLModelMeta, OptimizationRun)
- Session DB + TimescaleDB hypertable automatique
- NotificationService Telegram + Email
- RiskManager : Telegram réel, PnL hebdomadaire
- StrategyEngine : DataService wiring, prix réels depuis market_data
- FastAPI API : routes /health /ready /risk /positions /backtest /paper
- FastAPI lifespan : init DB + RiskManager

### À faire
1. BacktestEngine → DataService réel (remplacer fake data)
2. Dashboard Streamlit → appels httpx vers trading-api (remplacer données hardcodées)
3. MLEngine → StrategyEngine : signaux ML dans la boucle de trading
4. Walk-forward + Monte Carlo validation
5. IG Markets connector (Phase 5)