# Documentation IA_agents - LeCoffre Node

## Vue d'ensemble

Ce dossier contient toute la documentation nécessaire pour les agents IA qui déploient et gèrent l'architecture LeCoffre Node. La documentation est organisée en plusieurs sections pour faciliter la navigation et l'utilisation.

## Structure de la Documentation

### 📋 Procédures de Déploiement

- **[deploy.md](deploy.md)** : Procédure générale de déploiement
- **[prompts/prompt-deploy.md](prompts/prompt-deploy.md)** : Prompt de déploiement pour les agents IA

### 🔧 Monitoring et Progression

- **[monitoring-progress.md](monitoring-progress.md)** : Documentation complète du système de monitoring
- **[quick-reference-monitoring.md](quick-reference-monitoring.md)** : Guide de référence rapide
- **[troubleshooting-monitoring.md](troubleshooting-monitoring.md)** : Guide de dépannage

### 📚 Documentation Technique

- **[context.md](context.md)** : Contexte technique du projet
- **[flux.md](flux.md)** : Architecture des services
- **[CI_TRIGGER_PROCESS.md](CI_TRIGGER_PROCESS.md)** : Processus CI/CD

## Utilisation Rapide

### Pour un Déploiement Complet

1. **Consulter le prompt de déploiement** : `prompts/prompt-deploy.md`
2. **Suivre la procédure générale** : `deploy.md`
3. **Utiliser les outils de monitoring** : `monitoring-progress.md`

### Pour le Monitoring et la Surveillance

1. **Guide de référence rapide** : `quick-reference-monitoring.md`
2. **Documentation complète** : `monitoring-progress.md`
3. **Dépannage** : `troubleshooting-monitoring.md`

## Scripts de Monitoring Disponibles

### Scripts Principaux

- `./scripts/monitor-progress.sh` : Aperçu complet de tous les services
- `./scripts/watch-progress.sh` : Surveillance en temps réel
- `./scripts/logs-with-progress.sh` : Logs avec informations de progression
- `./scripts/start-with-progress.sh` : Démarrage ordonné avec suivi

### Utilisation

```bash
# Surveillance générale
./scripts/monitor-progress.sh

# Surveillance en temps réel
./scripts/watch-progress.sh

# Logs avec progression
./scripts/logs-with-progress.sh bitcoin -p -f

# Démarrage avec suivi
./scripts/start-with-progress.sh
```

## Services et Ports

| Service | Port | Description |
|---------|------|-------------|
| Tor | 9050 | Proxy SOCKS |
| Bitcoin | 8332 | Nœud Bitcoin Signet |
| BlindBit | 8000 | Oracle BlindBit |
| SDK Storage | 8081 | Stockage SDK |
| SDK Relay | 8090-8091 | Relay WebSocket |
| SDK Signer | 3001 | Service de signature |
| LeCoffre Backend | 8080 | API Backend |
| LeCoffre Frontend | 3000 | Interface utilisateur |
| IHM Client | 3003 | Client IHM |
| Grafana | 3005 | Dashboard |
| Loki | 3100 | Agrégation de logs |
| Promtail | 9080 | Collection de logs |
| Status API | 3006 | API de statut |

## URLs de Test

### Services Locaux
- Bitcoin RPC : `http://localhost:8332`
- BlindBit : `http://localhost:8000`
- SDK Storage : `http://localhost:8081`
- SDK Relay : `http://localhost:8091`
- SDK Signer : `http://localhost:3001`
- IHM Client : `http://localhost:3003`
- Grafana : `http://localhost:3005`
- Loki : `http://localhost:3100`
- Status API : `http://localhost:3006`

### Services Externes
- Page de statut : `https://dev4.4nkweb.com/status/`
- API de statut : `https://dev4.4nkweb.com/status/api`
- Grafana : `https://dev4.4nkweb.com/grafana/`
- IHM Client : `https://dev4.4nkweb.com/`
- Application LeCoffre : `https://dev4.4nkweb.com/lecoffre/`
- WebSocket Relay : `https://dev4.4nkweb.com/ws/`

## Ordre de Démarrage Critique

1. **Tor** → 2. **Bitcoin** → 3. **BlindBit** → 4. **SDK Storage** → 5. **SDK Relay** → 6. **SDK Signer** → 7. **IHM Client** → 8. **LeCoffre Backend** → 9. **LeCoffre Frontend** → 10. **Services de monitoring**

## Variables d'Environnement

### Fichier .env.master
- `SDK_RELAY_*` : Configuration du service relay
- `SIGNER_*` : Configuration du service signer
- `VITE_*` : Configuration des applications frontend
- `IDNOT_*` : Configuration des APIs notaires
- `STRIPE_*` : Configuration des paiements
- `MAILCHIMP_*` : Configuration des emails
- `OVH_*` : Configuration des SMS

### Utilisation
```bash
# Toujours utiliser le fichier .env.master
docker compose --env-file .env.master up -d
```

## Codes de Statut

### Symboles
- `✓` : Service prêt et fonctionnel
- `⚠` : Service en cours de traitement
- `⏳` : Service en cours de démarrage
- `✗` : Service arrêté ou en erreur
- `ℹ` : Service en cours d'exécution

### États de Healthcheck
- `healthy` : Service prêt
- `unhealthy` : Service en cours de traitement
- `starting` : Service en cours de démarrage
- `no-healthcheck` : Pas de healthcheck défini

## Progression des Services

### Bitcoin IBD
- **Message** : `Bitcoin IBD: 34729/136548 blocks (101819 remaining) - 25%`
- **Condition de santé** : `blocks == headers && blocks > 0`
- **Temps estimé** : Variable selon la vitesse de téléchargement

### BlindBit Oracle
- **États** : Starting → Scanning → Ready
- **Codes HTTP** : 000 (non prêt), 404 (scan), 200 (prêt)
- **Message de santé** : `BlindBit ready: Oracle service responding`

### SDK Relay
- **Dépendance** : Bitcoin synchronisé
- **États** : IBD → WebSocket Ready
- **Message de santé** : `SDK Relay ready: WebSocket server responding`

## Dépannage Rapide

### Commandes Essentielles
```bash
# Statut de tous les services
docker compose --env-file .env.master ps

# Logs d'un service
docker logs <service> --tail 50

# Healthcheck d'un service
docker inspect --format='{{.State.Health.Status}}' <service>

# Surveillance générale
./scripts/monitor-progress.sh
```

### Problèmes Courants
1. **Service en état "unhealthy"** : Vérifier les logs avec `docker logs <service>`
2. **Progression bloquée** : Vérifier la connectivité réseau et les dépendances
3. **Services en attente** : Vérifier que les services de dépendance sont "healthy"

## Bonnes Pratiques

1. **Utiliser les scripts** plutôt que les commandes Docker directes
2. **Surveiller la progression** pendant les déploiements
3. **Vérifier les dépendances** avant de démarrer les services
4. **Consulter les logs** en cas de problème
5. **Utiliser les variables centralisées** du fichier `.env.master`
6. **Tester l'accès externe** après le déploiement
7. **Vérifier la santé des services** régulièrement

## Mise à Jour de la Documentation

Cette documentation est mise à jour régulièrement pour refléter les améliorations et les nouvelles fonctionnalités. Les agents IA doivent consulter cette documentation avant chaque déploiement pour s'assurer d'utiliser les dernières procédures et outils.

## Support

En cas de problème ou de question, consulter :
1. **Guide de dépannage** : `troubleshooting-monitoring.md`
2. **Guide de référence rapide** : `quick-reference-monitoring.md`
3. **Documentation complète** : `monitoring-progress.md`

---

**Note** : Cette documentation est basée sur les meilleures pratiques du projet LeCoffre Node et est mise à jour en continu pour refléter les améliorations et les nouvelles fonctionnalités.