# Synthèse pour Agents IA - 4NK Environment

**Date** : 2025-01-27
**Version** : 1.0
**Usage** : Guide de synthèse pour les agents IA travaillant sur l'environnement 4NK

## 🎯 Contexte Général

### Environnement de Développement Centralisé
- **Machine principale** : dev4.4nkweb.com (LeCoffre)
- **Nœud de bootstrap** : dev3.4nkweb.com (signer centralisé, mini back)
- **Architecture** : 4NK modules + Projet LeCoffre (notaires)
- **Gestion des configurations** : 4NK_vault (API sécurisée)

## 🏗️ Architecture 4NK - Modules Principaux

### Services Core
1. **sdk_relay** (8090/8091) - Relais WebSocket central
2. **sdk_storage** (8081) - Stockage temporaire sécurisé
3. **sdk_signer** - Service de signature TypeScript
4. **sdk_client** - Client SDK (WASM)
5. **sdk_common** - Composants communs
6. **ihm_client** (3003) - Interface de gestion des clés

### Services Spécialisés
7. **4NK_vault** (6666) - API sécurisée de gestion des configurations
8. **4NK_certificator** - Ancrage cryptographique sur Bitcoin
9. **4NK_miner** - Service de minage (test)
10. **4NK_web_status** - Monitoring et statut
11. **blindbit-oracle** (8000) - Oracle Bitcoin Silent Payments
12. **rust-silentpayments** - Implémentation Silent Payments

## 🏢 Projet LeCoffre - Architecture Notariale

### Composants
- **lecoffre_node** - Docker de contrôle (orchestrateur principal)
- **lecoffre-front** - Frontend Next.js (interface notaires)
- **lecoffre-back-mini** - Backend centralisé (APIs externes)

### URLs et Services
- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre
- **4NK iframe** : https://dev4.4nkweb.com
- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires)
- **Mini back** : dev3.4nkweb.com (Stripe, Mailchimp, OVH, IdNot)

## 🔐 4NK_vault - Gestion Centralisée des Configurations

### Rôle Critique
- **API sécurisée** pour la gestion des configurations
- **Chiffrement quantique résistant** (ChaCha20-Poly1305)
- **Authentification par clés utilisateur**
- **Rotation automatique des clés** (toutes les heures)
- **Synchronisation** vers `confs/` dans le docker de contrôle

### Sécurité
- **Fichiers .env inaccessibles** pour des raisons de sécurité
- **Variables séparées** des secrets
- **Configurations déployées** dans `confs/` pour visualisation
- **Isolation par environnement** (dev, prod)

## 🚀 Déploiement par Phases - 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
```

### ✅ SCRIPTS OBLIGATOIRES
```bash
# Démarrage complet avec phases
./scripts/start-with-progress.sh

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

# Surveillance et validation
./scripts/monitor-progress.sh
./scripts/validate-deployment.sh
```

### Phases de Déploiement
1. **Phase 1** : Services de base (tor, sdk_storage, status-api)
2. **Phase 2** : Services blockchain (bitcoin → blindbit → sdk_relay)
3. **Phase 3** : Services applicatifs (lecoffre-front, ihm_client)
4. **Phase 4** : Services de monitoring (loki → promtail → grafana)
5. **Phase 5** : Services utilitaires (watchtower)

## 📊 Monitoring et Observabilité

### Stack de Monitoring
- **Grafana** : Dashboards et visualisation
- **Loki** : Collecte et stockage des logs
- **Promtail** : Agent de collecte des logs
- **Watchtower** : Mise à jour automatique

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

## 🔧 Scripts de Gestion

### Scripts Principaux
- `start.sh` - Démarrage complet avec phases
- `validate-deployment.sh` - Validation du déploiement
- `maintenance.sh` - Menu de maintenance interactif
- `backup-data.sh` - Sauvegarde des données
- `update-images.sh` - Mise à jour sécurisée

### Scripts de Monitoring
- `monitor-progress.sh` - Aperçu des services
- `watch-progress.sh` - Surveillance temps réel
- `logs-with-progress.sh` - Logs avec progression

## 📚 Documentation Centralisée

### Structure
- **IA_agents/** : Documentation pour les agents IA
- **docs/** : Documentation technique centralisée
- **ARCHITECTURE_ANALYSIS.md** : Analyse architecturale complète

### Documents Obligatoires
1. **ARCHITECTURE_ANALYSIS.md** - Analyse architecturale complète
2. **deployment-architecture.md** - Architecture de déploiement
3. **best-practices-deployment.md** - Bonnes pratiques
4. **README.md** - Documentation principale

## 🎯 Points Clés pour les Agents IA

### 1. **Respect des Phases**
- Services applicatifs indépendants du monitoring
- Démarrage séquentiel selon les dépendances
- Monitoring indépendant des applications

### 2. **Sécurité des Configurations**
- 4NK_vault pour la gestion centralisée
- Fichiers .env inaccessibles
- Configurations synchronisées vers confs/

### 3. **Scripts Spécialisés**
- Utilisation obligatoire des scripts fournis
- Interdiction des commandes Docker Compose directes
- Surveillance continue et diagnostic facilité

### 4. **Architecture Modulaire**
- Modules 4NK : SDK, services, monitoring
- Projet LeCoffre : Interface notariale
- 4NK_vault : Gestion centralisée des configurations

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

### En cas de problème :
1. Consulter `DEEP_ARCHITECTURE_ANALYSIS.md` pour l'analyse approfondie complète
2. Consulter `TECHNICAL_REFERENCE.md` pour la référence technique complète
3. Consulter `DEPLOYMENT_GUIDE.md` pour le guide de déploiement complet
4. Consulter `ARCHITECTURE_ANALYSIS.md` pour le contexte complet
5. Vérifier `best-practices-deployment.md` pour les bonnes pratiques
6. Utiliser les scripts de diagnostic spécialisés
7. 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-01-27**
**Version** : 1.0
**Usage** : Guide de synthèse obligatoire pour tous les agents IA