4NK_env/IA_agents/deployment-architecture.md

# Architecture de Déploiement LeCoffre Node

## 📋 Vue d'ensemble

Ce document définit l'architecture de déploiement optimale pour LeCoffre Node, basée sur le principe de séparation des responsabilités et l'ordre de démarrage par phases.

## 🏗️ Architecture par Phases

### **Principe Fondamental**
Les services sont organisés en 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

### **Phase 1: Services de Base (Parallèle)**
Ces services peuvent démarrer en parallèle car ils sont indépendants :

| Service | Port | Dépendance | Script |
|---------|------|------------|--------|
| **tor** | 9050 | Aucune | `start-with-progress.sh` |
| **sdk_storage** | 8081 | Aucune | `start-with-progress.sh` |
| **status-api** | 3006 | Aucune | `start-with-progress.sh` |

### **Phase 2: Services Blockchain (Séquentiel)**
Ces services suivent la chaîne blockchain :

| Service | Port | Dépendance | Script |
|---------|------|------------|--------|
| **bitcoin** | 8332 | tor (healthy) | `start-with-progress.sh` |
| **blindbit** | 8000 | bitcoin (healthy) | `start-with-progress.sh` |
| **sdk_relay** | 8090-8091 | blindbit (healthy) | `start-with-progress.sh` |

### **Phase 3: Services Applicatifs (Séquentiel)**
Ces services suivent la chaîne applicative :

| Service | Port | Dépendance | Script |
|---------|------|------------|--------|
| **ihm_client** | 3003 | sdk_relay + sdk_storage | `start-with-progress.sh` |

### **Phase 4: Services de Monitoring (Séquentiel, Indépendant)**
Ces services sont indépendants des applications :

| Service | Port | Dépendance | Script |
|---------|------|------------|--------|
| **loki** | 3100 | Aucune | `start-monitoring.sh` |
| **promtail** | 9080 | loki (healthy) | `start-monitoring.sh` |
| **grafana** | 3005 | loki + promtail (healthy) | `start-monitoring.sh` |

### **Phase 5: Services Utilitaires**
Services de maintenance et surveillance :

| Service | Port | Dépendance | Script |
|---------|------|------------|--------|
| **watchtower** | 8080 | Aucune | `start-with-progress.sh` |

## 🔧 Scripts de Déploiement

### **Scripts OBLIGATOIRES**

#### `./scripts/start-with-progress.sh`
**Usage** : Démarrage complet avec phases
**Fonction** : Démarre les services applicatifs dans l'ordre correct
**Phases** : 1, 2, 3, 5

#### `./scripts/start-monitoring.sh`
**Usage** : Démarrage monitoring indépendant
**Fonction** : Démarre les services de monitoring dans l'ordre correct
**Phases** : 4 uniquement

#### `./scripts/monitor-progress.sh`
**Usage** : Aperçu des services
**Fonction** : Affiche le statut de tous les services

#### `./scripts/watch-progress.sh`
**Usage** : Surveillance temps réel
**Fonction** : Surveillance continue avec rafraîchissement

#### `./scripts/logs-with-progress.sh`
**Usage** : Logs avec progression
**Fonction** : Affiche les logs avec informations de progression

### **Scripts INTERDITS**
```bash
# ❌ JAMAIS utiliser directement
docker compose --env-file .env.master up -d
docker compose up -d
docker compose start
```

## 📊 Flux de Déploiement

### **Déploiement Complet**
```bash
# 1. Démarrage services applicatifs
./scripts/start-with-progress.sh

# 2. Démarrage monitoring indépendant
./scripts/start-monitoring.sh

# 3. Surveillance
./scripts/monitor-progress.sh
```

### **Déploiement Monitoring Seul**
```bash
# Redémarrage monitoring sans impacter les applications
./scripts/start-monitoring.sh
```

### **Surveillance Continue**
```bash
# Surveillance temps réel
./scripts/watch-progress.sh

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

## 🎯 Avantages de cette Architecture

### **1. Séparation des Responsabilités**
- **Services applicatifs** : Fonctionnent même sans monitoring
- **Services de monitoring** : Peuvent être redémarrés sans impact
- **Dépendances claires** : Seules les dépendances métier

### **2. Optimisation du Démarrage**
- **Phase 1** : Services indépendants en parallèle
- **Phases 2-3** : Chaîne de dépendances respectée
- **Phase 4** : Monitoring indépendant
- **Phase 5** : Services utilitaires

### **3. Maintenance Facilitée**
- **Redémarrage monitoring** : Sans impact sur les applications
- **Redémarrage applications** : Sans impact sur le monitoring
- **Diagnostic** : Scripts spécialisés par fonction

### **4. Robustesse**
- **Isolation** : Pannes de monitoring n'impactent pas les applications
- **Récupération** : Redémarrage sélectif possible
- **Monitoring** : Surveillance continue et détaillée

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

## 📝 Validation

### **Tests de Déploiement**
1. **Services applicatifs** : URLs publiques accessibles
2. **Services de monitoring** : Dashboards Grafana alimentés
3. **Dépendances** : Chaîne de démarrage respectée
4. **Performance** : Temps de démarrage optimisé

### **Tests de Maintenance**
1. **Redémarrage monitoring** : Applications non impactées
2. **Redémarrage applications** : Monitoring non impacté
3. **Pannes sélectives** : Récupération isolée
4. **Surveillance** : Détection et diagnostic facilités

---

**Document créé le 2025-09-21**
**Version** : 1.0
**Architecture** : LeCoffre Node Deployment