# Documentation IA Agents - LeCoffre Node

## 📋 Vue d'ensemble

Ce répertoire contient toute la documentation nécessaire pour les agents IA travaillant sur le projet LeCoffre Node. Cette documentation est **OBLIGATOIRE** et doit être consultée avant tout déploiement.

## 📚 Documents Obligatoires

### **1. Documents de Contexte (À lire AVANT tout déploiement)**
- [`context.md`](context.md) - Contexte technique du projet
- [`flux.md`](flux.md) - Architecture des services et flux
- [`deploy.md`](deploy.md) - Procédures de déploiement détaillées

### **2. Documents de Processus**
- [`CI_TRIGGER_PROCESS.md`](CI_TRIGGER_PROCESS.md) - Processus de déclenchement des CI
- [`monitoring-progress.md`](monitoring-progress.md) - Système de monitoring et progression
- [`quick-reference-monitoring.md`](quick-reference-monitoring.md) - Guide de référence rapide

### **3. Documents d'Architecture (NOUVEAU)**
- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases
- [`best-practices-deployment.md`](best-practices-deployment.md) - Bonnes pratiques et interdictions

### **4. Documents de Déploiement**
- [`prompts/prompt-deploy.md`](prompts/prompt-deploy.md) - Prompt de déploiement complet

## 🚨 RÈGLES CRITIQUES

### **🚫 INTERDICTIONS ABSOLUES**
```bash
# ❌ JAMAIS utiliser ces commandes
docker compose --env-file .env.master up -d
docker compose up -d
docker compose start
```

### **✅ OBLIGATIONS ABSOLUES**
```bash
# ✅ Utiliser UNIQUEMENT ces scripts
./scripts/start-with-progress.sh    # Services applicatifs
./scripts/start-monitoring.sh       # Services de monitoring
./scripts/monitor-progress.sh       # Surveillance
```

## 🏗️ Architecture de Déploiement

### **Principe Fondamental**
Les services sont organisés en **5 phases** pour optimiser le démarrage et éviter les dépendances inutiles :

1. **Services applicatifs** : Fonctionnent indépendamment du monitoring
2. **Services de monitoring** : Observent sans impacter les applications
3. **Dépendances** : Seules les dépendances métier sont respectées

### **Ordre par Phases**
```
Phase 1: Services de Base (Parallèle)
├── tor, sdk_storage, sdk_signer, status-api

Phase 2: Services Blockchain (Séquentiel)
├── bitcoin → blindbit → sdk_relay

Phase 3: Services Applicatifs (Séquentiel)
├── lecoffre-back → lecoffre-front, ihm_client

Phase 4: Services de Monitoring (Séquentiel, Indépendant)
├── loki → promtail → grafana

Phase 5: Services Utilitaires
└── watchtower
```

## 🔧 Scripts de Déploiement

### **Scripts OBLIGATOIRES**
| Script | Usage | Phases |
|--------|-------|--------|
| `start-with-progress.sh` | Démarrage complet avec phases | 1, 2, 3, 5 |
| `start-monitoring.sh` | Démarrage monitoring indépendant | 4 |
| `monitor-progress.sh` | Aperçu des services | Toutes |
| `watch-progress.sh` | Surveillance temps réel | Toutes |
| `logs-with-progress.sh` | Logs avec progression | Toutes |

### **Scripts INTERDITS**
- `docker compose up -d` (toute variante)
- Commandes Docker Compose directes

## 📊 Avantages de cette Architecture

### **1. Robustesse**
- **Isolation** : Pannes de monitoring n'impactent pas les applications
- **Récupération** : Redémarrage sélectif possible
- **Stabilité** : Services applicatifs fonctionnent même sans monitoring

### **2. Performance**
- **Démarrage optimisé** : Services parallèles quand possible
- **Dépendances respectées** : Chaîne de démarrage optimale
- **Monitoring indépendant** : Ne ralentit pas les applications

### **3. Maintenance**
- **Redémarrage sélectif** : Monitoring ou applications séparément
- **Diagnostic facilité** : Scripts spécialisés par fonction
- **Surveillance continue** : Progression visible en temps réel

## 🎯 Workflow de Déploiement

### **Étape 1: Préparation**
1. Lire tous les documents de contexte
2. Vérifier la branche `ext`
3. Mettre à jour les dépendances
4. Synchroniser les configurations

### **Étape 2: Déploiement**
1. **Services applicatifs** : `./scripts/start-with-progress.sh`
2. **Services de monitoring** : `./scripts/start-monitoring.sh`
3. **Surveillance** : `./scripts/monitor-progress.sh`

### **Étape 3: Validation**
1. Tests des URLs publiques
2. Vérification des dashboards Grafana
3. Validation des flux fonctionnels
4. Documentation du retour d'expérience

## 📝 Documents de Retour d'Expérience

### **Format des REX**
- **Date** : Format ISO (YYYY-MM-DD)
- **Agent** : Nom de l'agent IA
- **Objectif** : But du déploiement
- **Statut** : Succès/Échec/Partiel
- **Problèmes** : Difficultés rencontrées
- **Solutions** : Actions correctives
- **Leçons** : Apprentissages

### **Exemple de REX**
- [`REX_Deploiement_2025-09-21.md`](REX_Deploiement_2025-09-21.md)

## 🔍 Points d'Attention

### **Dépendances Critiques**
1. **bitcoin** → **blindbit** → **sdk_relay** : Chaîne blockchain
2. **sdk_relay** → **lecoffre-back** → **lecoffre-front** : Chaîne applicative
3. **loki** → **promtail** → **grafana** : Chaîne monitoring

### **Healthchecks**
- Tous les services ont des healthchecks informatifs
- Les dépendances attendent que les services soient "healthy"
- Timeouts adaptés selon la criticité

### **Variables d'Environnement**
- Configuration centralisée dans `.env.master`
- Tous les scripts utilisent `--env-file .env.master`
- Pas de fichiers `.env` dispersés

## 🚨 Signaux d'Alerte

### **Si vous voyez ces commandes, c'est une ERREUR :**
```bash
docker compose --env-file .env.master up -d
docker compose up -d
docker compose start
```

### **Si vous voyez ces comportements, c'est une ERREUR :**
- Services de monitoring qui bloquent les applications
- Démarrage de tous les services en parallèle
- Absence de suivi de progression
- Logs sans informations de progression

### **Si vous voyez ces résultats, c'est CORRECT :**
- Phases de démarrage visibles
- Progression Bitcoin IBD affichée
- Services de monitoring indépendants
- Surveillance continue opérationnelle

## 📞 Support

### **En cas de problème :**
1. Consulter les documents de contexte
2. Vérifier les bonnes pratiques
3. Utiliser les scripts de diagnostic
4. Documenter le problème et la solution

### **Pour améliorer :**
1. Proposer des améliorations dans les REX
2. Mettre à jour la documentation
3. Tester les nouvelles approches
4. Valider avec l'équipe

---

**Document créé le 2025-09-21**  
**Version** : 1.0  
**Usage** : Obligatoire pour tous les agents IA  
**Mise à jour** : À chaque déploiement