4NK_env/IA_agents/AGENTS_SYNTHESIS.md

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

# ❌ JAMAIS utiliser ces commandes
docker compose --env-file .env.master up -d
docker compose up -d
docker compose start

✅ SCRIPTS OBLIGATOIRES

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

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