ihm_client/docs/INTEGRATION_4NK_NODE.md

# Intégration avec 4NK_node

## Vue d'ensemble

Ce document décrit l'intégration de `ihm_client` dans l'infrastructure `4NK_node` et les modifications apportées pour assurer une connectivité optimale avec les services backend.

## Architecture d'intégration

### Services connectés
- **SDK Relays** : Connexion WebSocket pour la synchronisation
- **Bitcoin Core** : API RPC pour les opérations blockchain
- **Blindbit Oracle** : API pour les oracles
- **Tor Proxy** : Proxy pour la confidentialité

### Ports et URLs
- Interface utilisateur : `http://localhost:8080`
- SDK Relay 1 : `ws://localhost:8090` (WebSocket)
- SDK Relay 2 : `ws://localhost:8092` (WebSocket)
- SDK Relay 3 : `ws://localhost:8094` (WebSocket)
- Bitcoin Core RPC : `http://localhost:18443`
- Blindbit Oracle : `http://localhost:8000`

## Modifications du script de démarrage

### Changements principaux

Le script `start.sh` a été modifié pour améliorer la robustesse et la connectivité :

#### 1. Vérification WebSocket des relays
```bash
# Vérification WebSocket des relays (optionnel)
check_websocket "sdk_relay WebSocket" "$SDK_RELAY_WS_URL"
```

#### 2. Suppression des dépendances critiques
- Les vérifications HTTP des relays ont été supprimées
- Les attentes critiques de Bitcoin Core et Blindbit ont été remplacées par des vérifications informatives
- L'interface utilisateur démarre maintenant même si certains services ne sont pas encore prêts

#### 3. Configuration dynamique
```bash
# Génération de la configuration dynamique
cat > /usr/share/nginx/html/config.js << EOF
window.ENV_CONFIG = {
    SDK_RELAY_WS_URL: '$SDK_RELAY_WS_URL',
    SDK_RELAY_HTTP_URL: '$SDK_RELAY_HTTP_URL',
    BITCOIN_RPC_URL: '$BITCOIN_RPC_URL',
    BLINDBIT_URL: '$BLINDBIT_URL',
    ENVIRONMENT: '4nk-node'
};
EOF
```

## Fonctionnalités de connectivité

### Reconnexion automatique
L'interface utilisateur gère automatiquement :
- La reconnexion aux WebSockets des relays
- La gestion des déconnexions temporaires
- La récupération après panne de service

### Gestion des erreurs
- Tentatives de reconnexion avec backoff exponentiel
- Logs détaillés pour le diagnostic
- Dégradation gracieuse en cas d'indisponibilité de service

## Tests de connectivité

### Test manuel des WebSockets
```bash
# Depuis le conteneur ihm_client
nc -z sdk_relay_1 8090
nc -z sdk_relay_2 8090
nc -z sdk_relay_3 8090
```

### Test de l'interface utilisateur
```bash
# Test HTTP
curl -s http://localhost:8080 | head -10

# Test de santé
curl -s http://localhost:8080/health
```

## Monitoring et logs

### Logs du conteneur
```bash
# Voir les logs de démarrage
docker logs 4nk-ihm-client

# Suivre les logs en temps réel
docker logs -f 4nk-ihm-client
```

### Métriques de santé
- Vérification périodique de nginx
- Statut des connexions WebSocket
- Disponibilité des services backend

## Dépannage

### Problèmes courants

#### 1. Interface utilisateur non accessible
```bash
# Vérifier le statut du conteneur
docker ps | grep ihm_client

# Vérifier les logs
docker logs 4nk-ihm-client --tail=20
```

#### 2. Connexion WebSocket échouée
```bash
# Vérifier la connectivité réseau
docker exec 4nk-ihm-client nc -z sdk_relay_1 8090

# Vérifier les logs des relays
docker logs sdk_relay_1 --tail=10
```

#### 3. Services backend indisponibles
```bash
# Vérifier Bitcoin Core
curl -s --user bitcoin:bitcoin http://localhost:18443

# Vérifier Blindbit
curl -s http://localhost:8000/health
```

### Solutions

#### Redémarrage du service
```bash
# Redémarrer ihm_client
docker-compose restart ihm_client

# Reconstruire et redémarrer
docker-compose build ihm_client
docker-compose up -d ihm_client
```

#### Nettoyage complet
```bash
# Arrêter tous les services
docker-compose down

# Nettoyer les volumes (optionnel)
docker-compose down -v

# Redémarrer
docker-compose up -d
```

## Configuration avancée

### Variables d'environnement
```bash
SDK_RELAY_WS_URL=ws://sdk_relay_1:8090
SDK_RELAY_HTTP_URL=http://sdk_relay_1:8091
BITCOIN_RPC_URL=http://bitcoin:18443
BLINDBIT_URL=http://blindbit:8000
```

### Personnalisation du script
Le script `start.sh` peut être modifié pour :
- Ajouter des vérifications de santé personnalisées
- Modifier les timeouts de connexion
- Ajouter des métriques de performance

## Sécurité

### Isolation réseau
- L'interface utilisateur est isolée dans le réseau Docker `btcnet`
- Communication sécurisée entre conteneurs
- Pas d'exposition directe des services backend

### Authentification
- Bitcoin Core utilise l'authentification par cookie
- Les WebSockets des relays sont sécurisés
- L'interface utilisateur gère l'authentification côté client

## Performance

### Optimisations
- Connexions WebSocket persistantes
- Mise en cache des données fréquemment utilisées
- Compression des données transmises

### Métriques
- Temps de réponse de l'interface
- Latence des WebSockets
- Utilisation des ressources

## Maintenance

### Mises à jour
```bash
# Mettre à jour l'image
docker-compose pull ihm_client

# Reconstruire avec les dernières modifications
docker-compose build ihm_client
```

### Sauvegarde
```bash
# Sauvegarder la configuration
docker cp 4nk-ihm-client:/usr/share/nginx/html/config.js ./backup/

# Sauvegarder les logs
docker logs 4nk-ihm-client > ./backup/ihm_client.log
```

## Support

Pour toute question ou problème lié à l'intégration :
1. Consulter les logs du conteneur
2. Vérifier la connectivité réseau
3. Tester les services backend individuellement
4. Consulter la documentation de `4NK_node`