ihm_client/docs/ARCHITECTURE.md

🏗️ Architecture Technique - ihm_client

Documentation technique détaillée de l'architecture de l'interface utilisateur ihm_client.

📋 Vue d'Ensemble

Architecture Générale

┌─────────────────────────────────────────────────────────────┐
│                    ihm_client                               │
├─────────────────────────────────────────────────────────────┤
│  Frontend (Vue.js + TypeScript)                            │
│  ├── Components Vue.js                                     │
│  ├── Services TypeScript                                   │
│  ├── Types et Interfaces                                   │
│  └── Utilitaires                                           │
├─────────────────────────────────────────────────────────────┤
│  WASM (Rust + sdk_client)                                  │
│  ├── Module WebAssembly                                    │
│  ├── Fonctions Silent Payments                             │
│  └── Interface JavaScript                                  │
├─────────────────────────────────────────────────────────────┤
│  Build System (Vite)                                       │
│  ├── Compilation TypeScript                                │
│  ├── Bundling et Optimisation                              │
│  └── Hot Module Replacement                                │
└─────────────────────────────────────────────────────────────┘

Stack Technologique

Couche	Technologie	Version	Rôle
Frontend	Vue.js	3.x	Framework UI
Language	TypeScript	5.x	Typage statique
Build	Vite	5.x	Build tool
WASM	Rust	1.70+	Logique métier
WASM Build	wasm-pack	0.12+	Compilation WASM
Styling	CSS3	-	Styles
Package Manager	npm	8.x+	Gestion dépendances

🏛️ Architecture Frontend

Structure des Composants

src/
├── components/              # Composants réutilisables
│   ├── header/             # En-tête de l'application
│   ├── modal/              # Modales et popups
│   ├── qrcode-scanner/     # Scanner QR code
│   └── validation-modal/   # Modales de validation
├── pages/                  # Pages de l'application
│   ├── home/              # Page d'accueil
│   ├── account/           # Gestion du compte
│   ├── signature/         # Signatures de documents
│   └── process-element/   # Gestion des processus
├── services/              # Services et APIs
│   ├── service.ts         # Service principal
│   ├── modal.service.ts   # Gestion des modales
│   ├── storage.service.ts # Gestion du stockage
│   └── token.ts           # Gestion des tokens
├── types/                 # Types TypeScript
│   ├── sdk_client.d.ts    # Types WASM
│   └── raw-imports.d.ts   # Types d'imports
└── utils/                 # Utilitaires
    ├── document.utils.ts  # Utilitaires documents
    ├── html.utils.ts      # Utilitaires HTML
    └── sp-address.utils.ts # Utilitaires Silent Payments

Architecture Vue.js

Composants Principaux

Header Component

interface HeaderProps {
  user: User;
  notifications: Notification[];
  onLogout: () => void;
}

Responsabilités :

• Navigation principale
• Affichage du profil utilisateur
• Gestion des notifications
• Menu de déconnexion

Modal Components

interface ModalProps {
  isOpen: boolean;
  title: string;
  content: string;
  onConfirm: () => void;
  onCancel: () => void;
}

Types de modales :

• Confirmation : Actions critiques
• Validation : Validation de données
• QR Scanner : Scanner de codes QR
• Profile : Édition du profil

QR Code Scanner

interface QRScannerProps {
  onScan: (data: string) => void;
  onError: (error: Error) => void;
  onClose: () => void;
}

Fonctionnalités :

• Accès à la caméra
• Détection de QR codes
• Validation des données
• Gestion des erreurs

Services et Communication

Service Principal

class Service {
  // Communication avec sdk_client WASM
  async generateWallet(): Promise<Wallet>;
  async lockUTXOs(wallet: Wallet, utxos: UTXO[]): Promise<boolean>;

  // Communication avec les APIs
  async sendMessage(message: Message): Promise<void>;
  async uploadDocument(file: File): Promise<Document>;

  // Gestion des données
  async saveData(key: string, data: any): Promise<void>;
  async loadData(key: string): Promise<any>;
}

Gestion des États

// Store global (Vuex/Pinia)
interface AppState {
  user: User | null;
  wallet: Wallet | null;
  processes: Process[];
  notifications: Notification[];
  settings: Settings;
}

⚡ Architecture WASM

Module sdk_client

Structure du Module

pkg/
├── sdk_client_bg.wasm     # Module WASM principal (3.3 MB)
├── sdk_client.d.ts        # Types TypeScript (12.6 KB)
├── sdk_client.js          # Wrapper JavaScript (182 B)
├── sdk_client_bg.js       # Code JavaScript généré (38 KB)
└── package.json           # Métadonnées du package

Fonctions Principales

Gestion des Wallets

// Rust (sdk_client)
pub fn generate_sp_wallet() -> Wallet {
    // Génération d'un nouveau wallet Silent Payment
}

pub fn lock_freezed_utxos(wallet: Wallet, utxos: Vec<UTXO>) -> bool {
    // Verrouillage des UTXOs gelés
}

Interface JavaScript

// TypeScript (ihm_client)
import { generate_sp_wallet, lock_freezed_utxos } from 'pkg/sdk_client';

const wallet = generate_sp_wallet();
const success = lock_freezed_utxos(wallet, utxos);

Intégration WASM-Frontend

Initialisation

// Initialisation du module WASM
import init from 'pkg/sdk_client';

async function initializeWASM() {
  try {
    await init();
    console.log('WASM module initialized');
  } catch (error) {
    console.error('Failed to initialize WASM:', error);
  }
}

Communication

// Appel de fonctions WASM
async function createWallet() {
  try {
    const wallet = generate_sp_wallet();
    return wallet;
  } catch (error) {
    console.error('WASM error:', error);
    throw error;
  }
}

🔧 Architecture Build

Configuration Vite

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import wasm from 'vite-plugin-wasm';

export default defineConfig({
  plugins: [
    vue(),
    wasm(),
  ],
  optimizeDeps: {
    exclude: ['pkg/sdk_client']
  },
  build: {
    target: 'es2020',
    rollupOptions: {
      output: {
        manualChunks: {
          'sdk-client': ['pkg/sdk_client']
        }
      }
    }
  }
});

Processus de Build

Développement

# Serveur de développement
npm run dev

# Hot Module Replacement activé
# Compilation TypeScript en temps réel
# Chargement WASM à la demande

Production

# Build optimisé
npm run build

# Optimisations :
# - Tree shaking
# - Code splitting
# - Minification
# - Compression gzip

Optimisations

Code Splitting

// Chargement à la demande des composants
const SignatureComponent = () => import('./pages/signature/signature-component.vue');
const AccountComponent = () => import('./pages/account/account-component.vue');

Lazy Loading WASM

// Chargement différé du module WASM
const loadWASM = async () => {
  if (!wasmModule) {
    wasmModule = await import('pkg/sdk_client');
    await wasmModule.default();
  }
  return wasmModule;
};

🔄 Flux de Données

Flux Principal

1. Utilisateur → Interface Vue.js
2. Interface → Services TypeScript
3. Services → Module WASM (sdk_client)
4. WASM → APIs externes (si nécessaire)
5. Réponse → Services → Interface → Utilisateur

Gestion des États

État Local (Composants)

// État local d'un composant
const componentState = reactive({
  loading: false,
  data: null,
  error: null
});

État Global (Store)

// Store global de l'application
const appStore = {
  user: ref<User | null>(null),
  wallet: ref<Wallet | null>(null),
  processes: ref<Process[]>([]),
  notifications: ref<Notification[]>([])
};

Persistance

// Sauvegarde locale
localStorage.setItem('user-data', JSON.stringify(userData));

// Synchronisation avec le serveur
await service.syncData(userData);

🔒 Architecture de Sécurité

Sécurité Frontend

Validation des Entrées

// Validation côté client
function validateUserInput(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

// Sanitisation HTML
function sanitizeHTML(html: string): string {
  return DOMPurify.sanitize(html);
}

Protection XSS

// Échappement des données
function escapeHTML(text: string): string {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

Sécurité WASM

Gestion de la Mémoire

// Rust - Gestion sûre de la mémoire
pub fn process_data(data: Vec<u8>) -> Result<Vec<u8>, Error> {
    // Validation des données d'entrée
    if data.len() > MAX_SIZE {
        return Err(Error::DataTooLarge);
    }

    // Traitement sécurisé
    let result = process_secure(data)?;
    Ok(result)
}

Protection des Clés

// Protection des clés privées
pub struct SecureWallet {
    private_key: SecureString,
    public_key: String,
}

impl SecureWallet {
    pub fn new() -> Self {
        let private_key = generate_secure_key();
        let public_key = derive_public_key(&private_key);

        Self {
            private_key: SecureString::new(private_key),
            public_key,
        }
    }
}

📊 Architecture de Performance

Métriques de Performance

Temps de Chargement

• Premier rendu : < 2s
• Interactivité : < 3s
• Chargement complet : < 5s

Optimisations

Bundle Size

# Taille des bundles
dist/
├── index.js              # ~300 KB (gzippé)
├── sdk_client.wasm       # ~3.3 MB (gzippé)
└── vendor.js             # ~200 KB (gzippé)

Lazy Loading

// Chargement à la demande
const routes = [
  {
    path: '/signature',
    component: () => import('./pages/signature.vue')
  }
];

Caching

// Cache du module WASM
const wasmCache = new Map();

async function getWASMModule() {
  if (wasmCache.has('sdk_client')) {
    return wasmCache.get('sdk_client');
  }

  const module = await loadWASMModule();
  wasmCache.set('sdk_client', module);
  return module;
}

🔍 Monitoring et Observabilité

Logs et Debugging

Logs Frontend

// Logging structuré
const logger = {
  info: (message: string, data?: any) => {
    console.log(`[INFO] ${message}`, data);
  },
  error: (message: string, error?: Error) => {
    console.error(`[ERROR] ${message}`, error);
  }
};

Logs WASM

// Logging Rust
use log::{info, error};

pub fn process_wallet() -> Result<Wallet, Error> {
    info!("Starting wallet processing");

    match process_secure() {
        Ok(wallet) => {
            info!("Wallet processed successfully");
            Ok(wallet)
        },
        Err(e) => {
            error!("Wallet processing failed: {}", e);
            Err(e)
        }
    }
}

Métriques

Métriques Frontend

• Temps de rendu : Performance des composants
• Temps de réponse : Réactivité de l'interface
• Utilisation mémoire : Consommation RAM
• Erreurs JavaScript : Stabilité de l'application

Métriques WASM

• Temps d'initialisation : Chargement du module
• Temps d'exécution : Performance des fonctions
• Utilisation mémoire : Gestion de la mémoire
• Erreurs Rust : Stabilité du module

🚀 Déploiement

Environnements

Développement

# Serveur de développement
npm run dev

# Variables d'environnement
NODE_ENV=development
VITE_API_URL=http://localhost:8091
VITE_WS_URL=ws://localhost:8090

Production

# Build de production
npm run build

# Variables d'environnement
NODE_ENV=production
VITE_API_URL=https://api.4nkweb.com
VITE_WS_URL=wss://ws.4nkweb.com

Intégration 4NK_node

Artefacts et serveur

• Le Dockerfile de ihm_client produit uniquement les artefacts dist/.
• Le serveur (Nginx) est géré par 4NK_node qui consomme dist/.

Variables d'Environnement

# Configuration pour 4NK_node
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

🔮 Évolutions Futures

Améliorations Planifiées

Performance

• Web Workers : Traitement en arrière-plan
• Service Workers : Cache et offline
• WebAssembly SIMD : Optimisations vectorielles

Fonctionnalités

• PWA : Application web progressive
• Offline Mode : Fonctionnement hors ligne
• Real-time Sync : Synchronisation temps réel

Sécurité

• Hardware Security : Intégration TPM/SE
• Multi-factor Auth : Authentification à deux facteurs
• Audit Trail : Traçabilité complète

---

🏗️ Architecture ihm_client - Conçue pour la performance et la sécurité 🚀