# 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)**
- [`../docs/DEEP_ARCHITECTURE_ANALYSIS.md`](../docs/DEEP_ARCHITECTURE_ANALYSIS.md) - **NOUVEAU** - Analyse architecturale approfondie complète
- [`../docs/TECHNICAL_REFERENCE.md`](../docs/TECHNICAL_REFERENCE.md) - **NOUVEAU** - Référence technique complète
- [`../docs/DEPLOYMENT_GUIDE.md`](../docs/DEPLOYMENT_GUIDE.md) - **NOUVEAU** - Guide de déploiement complet
- [`../docs/ARCHITECTURE_ANALYSIS.md`](../docs/ARCHITECTURE_ANALYSIS.md) - Analyse architecturale complète
- [`../docs/context.md`](../docs/context.md) - Contexte technique du projet
- [`../docs/flux.md`](../docs/flux.md) - Architecture des services et flux
- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases

### **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**
- [`../docs/DEEP_ARCHITECTURE_ANALYSIS.md`](../docs/DEEP_ARCHITECTURE_ANALYSIS.md) - **NOUVEAU** - Analyse architecturale approfondie complète
- [`../docs/ARCHITECTURE_ANALYSIS.md`](../docs/ARCHITECTURE_ANALYSIS.md) - Analyse architecturale complète 4NK + LeCoffre
- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases
- [`best-practices-deployment.md`](best-practices-deployment.md) - Bonnes pratiques et interdictions
- [`blindbit-oracle-deployment.md`](blindbit-oracle-deployment.md) - Déploiement et configuration BlindBit Oracle

#### État d'avancement (services)
- ✅ Ajout et publication du service `4NK_certificator` (ancrage mensuel on-chain)
  - Repo: `https://git.4nkweb.com/4nk/4NK_certificator`
  - Spécification: `docs/CERTIFICATOR_SPECIFICATION.md`
  - Déploiement: `lecoffre_node/docker-compose.certificator.yml`

### **4. Documents de Déploiement**
- [`prompts/prompt-deploy.md`](prompts/prompt-deploy.md) - Prompt de déploiement complet
- **Scripts centralisés** : Tous les scripts d'agents IA sont maintenant dans `projects/lecoffre/lecoffre_node/scripts/`

## 🔐 Synchronisation des configurations (Vault)

```bash
bash projects/lecoffre/lecoffre_node/scripts/sync-vault-full.sh
```
Résultats attendus:
- `vault/confs2/` (miroir local)
- `confs/` (copie centralisée)
- `projects/lecoffre/lecoffre_node/confs/` (réplication projet)

## 🧹 Standardisation des fichiers ignore

```bash
bash projects/lecoffre/lecoffre_node/scripts/sync-ignore-files.sh
```
Portée:
- `4NK_modules/*` (exclu: `4NK_vault`)
- `projects/*/*`

## 🚨 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 (NOUVEAU - centralisés)
cd projects/lecoffre/lecoffre_node
./scripts/start.sh                  # Démarrage séquentiel avec progression
./scripts/validate-deployment.sh    # Validation complète
./scripts/maintenance.sh            # Menu de maintenance interactif
./scripts/backup-data.sh            # Sauvegarde des données
./scripts/update-images.sh          # Mise à jour sécurisée
```

## 🏗️ 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, status-api

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

Phase 3: Services Applicatifs (Séquentiel)
├── 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** (centralisés dans `projects/lecoffre/lecoffre_node/scripts/`)
| 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-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

### **Configuration Loki (CRITIQUE)**
- **OBLIGATOIRE** : `http_listen_address: 0.0.0.0` (pas 127.0.0.1)
- **OBLIGATOIRE** : `instance_addr: 0.0.0.0` (pas 127.0.0.1)
- **Fichier** : `/conf/loki/loki-config.yaml` avec configuration complète
- **Healthcheck** : Utiliser `wget` (pas `curl`)

## 🚨 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

---

## 🔧 Scripts de déploiement (nouveau)

Exécuter depuis `4NK_env/`.

- Sync des configurations depuis le Vault vers `confs/`:
```sh
sh IA_agents/prompts/prompt-deploy/scripts/sync-vault-full.sh
```
Prérequis: `vault/.env` (VAULT_BASE_URL, VAULT_USER|VAULT_USER_ID, VAULT_ENV).

- Déploiement séquencé de tous les services (respect des phases et healthchecks):
```sh
sh IA_agents/prompts/prompt-deploy/scripts/deploy-all.sh
```
Affiche la progression Tor (bootstrap %), Bitcoin (sync), BlindBit (sync/scan), Relay (scan), puis vérifie ports et URLs internes/externes.

- Vérification rapide de la santé:
```sh
sh IA_agents/prompts/prompt-deploy/scripts/quick-health-check.sh
```

Ces scripts remplacent tout usage d’un `docker compose up` global pour garantir l’ordre par phases et la lisibilité de la progression.

### Emplacements standards (déploiement)
- Confs: `/home/debian/4NK_env/lecoffre_node/confs/`
- Logs: `/home/debian/4NK_env/lecoffre_node/logs/`
- Data: `/home/debian/4NK_env/lecoffre_node/data/`
- Backups: `/home/debian/4NK_env/lecoffre_node/backups/`