4nk/4NK_env
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_env/docs/DEEP_ARCHITECTURE_ANALYSIS.md

17 KiB
Raw Permalink Blame History

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

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