# 🏗️ 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
```typescript
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
```typescript
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
```typescript
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
```typescript
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

```typescript
// 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
// 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
// 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
```typescript
// 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
```typescript
// 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

```typescript
// 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
```bash
# Serveur de développement
npm run dev

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

#### Production
```bash
# Build optimisé
npm run build

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

### Optimisations

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

#### Lazy Loading WASM
```typescript
// 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)
```typescript
// État local d'un composant
const componentState = reactive({
  loading: false,
  data: null,
  error: null
});
```

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

#### Persistance
```typescript
// 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
```typescript
// 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
```typescript
// É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
// 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
```rust
// 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
```bash
# Taille des bundles
dist/
├── index.js              # ~300 KB (gzippé)
├── sdk_client.wasm       # ~3.3 MB (gzippé)
└── vendor.js             # ~200 KB (gzippé)
```

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

##### Caching
```typescript
// 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
```typescript
// 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
```rust
// 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
```bash
# 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
```bash
# 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
```bash
# 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é** 🚀