# Analyse Architecturale Approfondie - 4NK Environment

**Date** : 2025-01-27
**Version** : 2.0
**Contexte** : Analyse approfondie de l'architecture 4NK et du projet LeCoffre

## 📋 Vue d'ensemble Détaillée

Cette analyse approfondie présente l'architecture complète de l'environnement 4NK, incluant tous les modules, leurs dépendances, configurations, et le système de déploiement par phases.

## 🏗️ Architecture Générale Détaillée

### Structure des Submodules
```
4NK_env/                           # Environnement centralisé
├── 4NK_modules/                   # 13 modules 4NK (SDK, services)
│   ├── sdk_relay/                 # Relais WebSocket central (Rust)
│   ├── sdk_storage/               # Stockage temporaire (Rust)
│   ├── sdk_signer/                # Service de signature (TypeScript)
│   ├── sdk_client/                # Client SDK (Rust/WASM)
│   ├── sdk_common/                # Composants communs (Rust)
│   ├── sdk-signer-client/         # Client signeur (TypeScript)
│   ├── ihm_client/                # Interface utilisateur (Vite/React)
│   ├── 4NK_vault/                 # API sécurisée configurations (Python)
│   ├── 4NK_certificator/          # Ancrage cryptographique (Rust)
│   ├── 4NK_miner/                 # Service de minage (Rust)
│   ├── 4NK_web_status/            # Service de statut (Python)
│   ├── blindbit-oracle/           # Oracle Bitcoin (Rust)
│   ├── rust-silentpayments/       # Silent Payments (Rust)
│   └── doc_api/                   # Documentation API
├── projects/lecoffre/              # Projet LeCoffre (notaires)
│   ├── lecoffre_node/             # Docker de contrôle
│   ├── lecoffre-front/             # Frontend Next.js
│   └── lecoffre-back-mini/         # Backend centralisé
├── IA_agents/                      # Agents IA et documentation
├── docs/                          # Documentation centralisée
├── scripts/                       # Scripts de gestion centralisés
└── confs/                         # Configurations déployées (4NK_vault)
```

## 🔧 Modules 4NK - Analyse Approfondie

### 1. **sdk_relay** - Service de Relais WebSocket Central
**Rôle** : Relais central pour les communications WebSocket et la synchronisation mesh
- **Technologie** : Rust (tokio, async-trait, futures-util)
- **Ports** : 8090 (WebSocket), 8091 (HTTP health)
- **Dépendances** :
  - `sdk_common` (git: https://git.4nkweb.com/4nk/sdk_common.git)
  - `bitcoincore-rpc` (0.18) - Interface Bitcoin Core
  - `tokio-tungstenite` (0.21.0) - WebSocket
  - `zeromq` (0.4.1) - ZMQ Bitcoin Core
- **Fonctionnalités** :
  - Serveur WebSocket configurable
  - Synchronisation mesh entre relais
  - Gestion des processus et membres
  - Interface avec Bitcoin Core (RPC + ZMQ)
  - Intégration Blindbit pour Silent Payments
  - Cache de déduplication
  - Gestion d'état locale dans `~/<data_dir>`
- **Architecture** : Rust avec gestion d'état locale
- **Configuration** : Fichier de configuration via `--config`
- **Healthcheck** : `/health` sur port 8091

### 2. **sdk_storage** - Service de Stockage Temporaire Sécurisé
**Rôle** : Stockage temporaire avec TTL et chiffrement
- **Technologie** : Rust (tide, async-std)
- **Port** : 8081 (mappé depuis 8080)
- **API** :
  - `POST /store` : Stockage avec clé/valeur/TTL
  - `GET /retrieve/:key` : Récupération des données
- **Fonctionnalités** :
  - Stockage temporaire avec expiration
  - Clés hexadécimales 64 caractères
  - Valeurs hexadécimales
  - TTL optionnel (permanent si non spécifié)
  - Chiffrement des données
- **Architecture** : Rust avec async-std
- **Healthcheck** : `/health` sur port 8080

### 3. **sdk_signer** - Service de Signature TypeScript
**Rôle** : Service de signature pour l'écosystème 4NK
- **Technologie** : TypeScript avec support WASM
- **Fonctionnalités** :
  - Gestion des processus et signatures
  - Communication sécurisée
  - Compatibilité WASM (stub temporaire)
  - Interface avec le réseau de relais
  - Validation des permissions
- **Architecture** : TypeScript avec support WASM
- **État** : Compatible avec stub sdk_client
- **Dépendances** : Node.js 18+, npm/yarn

### 4. **sdk_client** - Client SDK Rust/WASM
**Rôle** : Client SDK pour l'interaction avec l'écosystème 4NK
- **Technologie** : Rust avec interface WebAssembly
- **Fonctionnalités** :
  - Interface avec les services 4NK
  - Gestion des connexions WebSocket
  - Support des processus et transactions
  - Compilation WASM pour le web
- **Architecture** : Rust avec interface WASM
- **Usage** : Importé par sdk_signer et autres clients

### 5. **sdk_common** - Bibliothèque Commune
**Rôle** : Composants communs partagés entre tous les modules
- **Technologie** : Rust
- **Fonctionnalités** :
  - Types et structures communes
  - Utilitaires partagés
  - Protocoles de communication
  - Support Blindbit (feature: "blindbit-backend")
  - Support parallèle (feature: "parallel")
- **Usage** : Importé par tous les autres modules
- **Features** : parallel, blindbit-backend

### 6. **sdk-signer-client** - Client Signeur
**Rôle** : Client pour l'interaction avec le service de signature
- **Technologie** : TypeScript
- **Fonctionnalités** :
  - Interface avec sdk_signer
  - Gestion des signatures
  - Communication sécurisée
- **Architecture** : TypeScript client

### 7. **ihm_client** - Interface Homme-Machine
**Rôle** : Interface utilisateur pour la gestion des clés et processus
- **Technologie** : Vite + React
- **Port** : 3003
- **Fonctionnalités** :
  - Interface de gestion des clés Bitcoin
  - Gestion des processus
  - Interface utilisateur web
  - Variables d'environnement Vite
- **Dépendances** : sdk_relay, sdk_storage
- **Variables** : VITE_JWT_SECRET_KEY, VITE_API_BASE_URL, VITE_WS_URL, VITE_STORAGE_URL, VITE_SIGNER_URL, VITE_BOOTSTRAPURL

### 8. **4NK_vault** - Système de Gestion des Configurations
**Rôle** : API sécurisée pour la gestion centralisée des configurations
- **Technologie** : Python Flask
- **Port** : 6666 (HTTPS)
- **Sécurité** :
  - Authentification par clés utilisateur
  - Chiffrement quantique résistant (ChaCha20-Poly1305)
  - Rotation automatique des clés (toutes les heures)
  - Isolation par environnement (dev, prod)
- **Fonctionnalités** :
  - Résolution des variables d'environnement
  - Synchronisation vers `confs/` dans le docker de contrôle
  - Protection des secrets
  - Clés individuelles par utilisateur/environnement
- **Endpoints** :
  - `GET /health` - Contrôle de santé
  - `GET /info` - Informations API
  - `GET /routes` - Routes disponibles
  - `GET /<env>/<file>` - Fichier chiffré
- **Déploiement** : Synchronise les configurations vers `confs/`

### 9. **4NK_certificator** - Service d'Ancrage Cryptographique
**Rôle** : Ancrage périodique sur Bitcoin mainnet des empreintes des échanges
- **Technologie** : Rust
- **Fonctionnalités** :
  - Surveillance des messages du relay 4NK
  - Détection des paiements Bitcoin
  - Enregistrement périodique sur blockchain
  - Métriques de volume de données
  - Base de données SQLite
- **Architecture** : Rust avec base de données SQLite
- **État** : MVP complet implémenté
- **Composants** :
  - RelayMonitor (surveillance WebSocket)
  - PaymentWatcher (surveillance Bitcoin)
  - Base de données SQLite

### 10. **4NK_miner** - Service de Minage
**Rôle** : Service de minage Bitcoin (développement/test)
- **Technologie** : Rust
- **Fonctionnalités** :
  - Minage sur réseau Signet
  - Génération de blocs de test
  - Interface avec le réseau Bitcoin
- **Usage** : Développement et tests uniquement

### 11. **4NK_web_status** - Service de Statut
**Rôle** : Service de monitoring et statut des services
- **Technologie** : Python Flask
- **Port** : 3006
- **Fonctionnalités** :
  - Monitoring des services
  - Interface de statut
  - Métriques de santé
  - API REST pour le statut
- **Dépendances** : Docker socket, logs directory

### 12. **blindbit-oracle** - Oracle Bitcoin Silent Payments
**Rôle** : Service pour les paiements silencieux (Silent Payments)
- **Technologie** : Rust
- **Port** : 8000
- **Fonctionnalités** :
  - Génération d'adresses Silent Payments
  - Validation des transactions
  - Interface HTTP REST
  - Scan filtré BIP158
- **Dépendances** : Bitcoin Core
- **Configuration** : blindbit.toml

### 13. **rust-silentpayments** - Implémentation Silent Payments
**Rôle** : Implémentation Rust des Silent Payments
- **Technologie** : Rust
- **Fonctionnalités** :
  - Génération d'adresses Silent Payments
  - Validation des transactions
  - Utilitaires cryptographiques
- **Usage** : Bibliothèque pour blindbit-oracle

## 🏢 Projet LeCoffre - Architecture Notariale Détaillée

### Contexte Métier
Le projet LeCoffre est une plateforme de gestion de documents sécurisée pour les notaires, utilisant l'infrastructure 4NK pour la sécurité et l'intégrité des documents.

### Composants du Projet LeCoffre

#### 1. **lecoffre_node** - Orchestrateur Principal
**Rôle** : Docker de contrôle et déploiement pour LeCoffre
- **Architecture** : Docker Compose avec Nginx intégré
- **Services déployés** :
  - **tor** (btcpayserver/tor:0.4.8.10) - Proxy anonyme
  - **bitcoin** (build: ./bitcoin) - Nœud Bitcoin Signet
  - **blindbit** (git.4nkweb.com/4nk/blindbit-oracle:fixed-source) - Oracle Bitcoin
  - **sdk_relay** (git.4nkweb.com/4nk/sdk_relay:ext) - Relais WebSocket
  - **sdk_storage** (git.4nkweb.com/4nk/sdk_storage:ext) - Stockage temporaire
  - **lecoffre-front** (git.4nkweb.com/4nk/lecoffre-front:ext) - Frontend Next.js
  - **ihm_client** (git.4nkweb.com/4nk/ihm_client:ext) - Interface utilisateur
  - **grafana** (grafana/grafana:latest) - Monitoring
  - **loki** (grafana/loki:latest) - Collecte de logs
  - **promtail** (grafana/promtail:latest) - Agent de collecte
  - **status-api** (build: 4NK_web_status) - API de statut
  - **watchtower** (containrrr/watchtower) - Mise à jour automatique
  - **signet_miner** (build: 4NK_miner) - Minage (profile: miner)
- **Configuration** : Centralisée dans `confs/` (synchronisée depuis 4NK_vault)
- **Déploiement** : Scripts automatisés avec phases de démarrage
- **Réseau** : btcnet (172.20.0.0/16)
- **Volumes** : Persistance des données (bitcoin_data, blindbit_data, sdk_data, etc.)

#### 2. **lecoffre-front** - Interface Utilisateur
**Rôle** : Frontend Next.js pour l'application LeCoffre
- **Technologie** : Next.js avec React
- **Port** : 3004 (mappé depuis 8080)
- **Fonctionnalités** :
  - Interface utilisateur pour les notaires
  - Gestion des documents
  - Intégration avec l'écosystème 4NK
  - Variables d'environnement Next.js
- **Variables** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_4NK_IFRAME_URL, NEXT_PUBLIC_IDNOT_BASE_URL
- **Déploiement** : Conteneur Docker sur port 3004
- **User** : lecoffreuser (non-root)

#### 3. **lecoffre-back-mini** - Backend Centralisé
**Rôle** : Backend centralisé pour les besoins spécifiques des notaires
- **Déploiement** : Sur dev3.4nkweb.com
- **Fonctionnalités** :
  - APIs avec Stripe (paiements)
  - Intégration Mailchimp (email marketing)
  - Intégration OVH (SMS)
  - Intégration IdNot (HMR dev3 ↔ dev4 via OAuth2)
- **Architecture** : Service centralisé indépendant
- **APIs** :
  - `/api/v1/health` - Santé du service
  - `/api/v1/status` - Statut du service
  - `/api/v1/idnot/state` - État IdNot

## 🌐 Architecture de Déploiement Détaillée

### Environnements et URLs
- **dev4.4nkweb.com** : Machine principale (LeCoffre)
- **dev3.4nkweb.com** : Nœud de bootstrap (signer centralisé, mini back)

### 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 (APIs Stripe, Mailchimp, OVH, IdNot)

### Architecture de Déploiement par Phases

#### Phase 1: Services de Base (Parallèle)
- **tor** : Proxy anonyme (btcpayserver/tor:0.4.8.10)
- **sdk_storage** : Stockage temporaire (git.4nkweb.com/4nk/sdk_storage:ext)
- **status-api** : API de statut (build: 4NK_web_status)

#### Phase 2: Services Blockchain (Séquentiel)
- **bitcoin** → **blindbit** → **sdk_relay**
- Chaîne de dépendances blockchain respectée

#### Phase 3: Services Applicatifs (Séquentiel)
- **lecoffre-front** : Frontend Next.js
- **ihm_client** : Interface utilisateur
- Dépendances : sdk_relay + sdk_storage

#### Phase 4: Services de Monitoring (Indépendant)
- **loki** → **promtail** → **grafana**
- Chaîne de dépendances monitoring

#### Phase 5: Services Utilitaires
- **watchtower** : Mise à jour automatique (interval: 30s)

## 🔐 Sécurité et Configuration Détaillée

### 4NK_vault - Gestion Centralisée des Configurations
- **Rôle** : API sécurisée pour la gestion des configurations
- **Sécurité** :
  - Chiffrement quantique résistant (ChaCha20-Poly1305)
  - Authentification par clés utilisateur
  - Rotation automatique des clés (toutes les heures)
  - Isolation par environnement (dev, prod)
- **Déploiement** : Synchronise vers `confs/` dans le docker de contrôle
- **Protection des secrets** : Fichiers .env inaccessibles, variables séparées

### Variables d'Environnement par Service
- **bitcoin** : BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD, BITCOIN_RPC_PORT
- **blindbit** : BLINDBIT_API_PORT, BITCOIN_RPC_URL
- **sdk_relay** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL
- **sdk_storage** : STORAGE_PORT, STORAGE_DATA_DIR
- **lecoffre-front** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_IDNOT_BASE_URL
- **ihm_client** : VITE_API_URL, VITE_4NK_URL, VITE_RELAY_URL
- **grafana** : GF_SECURITY_ADMIN_PASSWORD, GF_DATABASE_TYPE
- **loki** : LOKI_CONFIG_FILE, LOKI_DATA_DIR
- **promtail** : PROMTAIL_CONFIG_FILE, LOKI_URL
- **status-api** : STATUS_API_PORT, STATUS_API_HOST

## 📊 Monitoring et Observabilité Détaillée

### Stack de Monitoring
- **Grafana** (grafana/grafana:latest) : Dashboards et visualisation
- **Loki** (grafana/loki:latest) : Collecte et stockage des logs
- **Promtail** (grafana/promtail:latest) : Agent de collecte des logs
- **Watchtower** (containrrr/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`
- **Healthcheck** : `wget` (pas `curl`)

### Dashboards Disponibles
- Vue d'ensemble LeCoffre
- Bitcoin & Miner
- Services Applications
- SDK Services
- Frontend Services

### Logs Centralisés
- **Répertoire** : `/home/debian/4NK_env/projects/lecoffre/lecoffre_node/logs/`
- **Services** : tor, bitcoin, blindbit, sdk_relay, sdk_storage, lecoffre-front, ihm_client, grafana, loki, promtail, status-api
- **Collecte** : Promtail → Loki → Grafana

## 🔄 CI/CD et Déploiement Détaillé

### Branches et Tags
- **Branche unifiée** : `ext` pour tous les dépôts 4NK
- **Branches spéciales** : `main` pour 4NK_certificator, 4NK_miner, 4NK_web_status
- **Tag Docker** : `ext` pour toutes les images
- **Déclenchement** : Push sur `ext` → Build automatique

### Scripts de Déploiement Détaillés
- **start.sh** : Démarrage complet avec phases et progression
- **validate-deployment.sh** : Validation complète du déploiement
- **maintenance.sh** : Menu de maintenance interactif
- **backup-data.sh** : Sauvegarde des données
- **update-images.sh** : Mise à jour sécurisée
- **collect-logs.sh** : Collecte des logs
- **deploy-grafana.sh** : Déploiement du monitoring
- **sync-configs.sh** : Synchronisation des configurations

### Healthchecks Détaillés
- **tor** : tor-progress.sh (bootstrap %)
- **bitcoin** : bitcoin-progress.sh (IBD, blocks, headers)
- **blindbit** : blindbit-progress.sh (API, scan)
- **sdk_relay** : sdk-relay-progress.sh (WebSocket, health)
- **sdk_storage** : curl /health
- **lecoffre-front** : ps aux | grep next-server
- **ihm_client** : curl localhost:3003
- **grafana** : curl /api/health
- **loki** : wget /ready
- **promtail** : fichier positions.yaml
- **status-api** : curl /api

## 🎯 Points Clés de l'Architecture Approfondie

### 1. **Séparation des Responsabilités**
- Services applicatifs indépendants du monitoring
- Monitoring observant sans impacter
- Dépendances uniquement métier

### 2. **Sécurité Multi-Niveaux**
- 4NK_vault pour la gestion centralisée des configurations
- Chiffrement quantique résistant
- Isolation des secrets et variables
- Utilisateurs non-root dans les conteneurs

### 3. **Déploiement Optimisé**
- Phases de démarrage respectées
- Scripts spécialisés obligatoires
- Surveillance continue et diagnostic facilité
- Healthchecks informatifs

### 4. **Maintenance Facilitée**
- Redémarrage sélectif possible
- Scripts de maintenance interactifs
- Documentation centralisée et à jour
- Logs centralisés et structurés

### 5. **Architecture Modulaire**
- 13 modules 4NK avec rôles spécialisés
- Projet LeCoffre : Interface notariale
- 4NK_vault : Gestion centralisée des configurations
- Scripts centralisés et réutilisables

---

**Document créé le 2025-01-27**
**Version** : 2.0
**Usage** : Analyse architecturale approfondie pour les agents IA et l'équipe de développement