📡 Communication entre Services

Architecture de communication et patterns utilisés dans Commerce Tracking.

🎯 Vue d'ensemble

Commerce Tracking utilise NATS comme message broker pour la communication asynchrone entre les microservices. Cette approche garantit la scalabilité, la résilience et la découplage des services.

Avantages de NATS

Performance : Très faible latence (< 1ms)
Simplicité : API simple et intuitive
Scalabilité : Support de millions de messages/seconde
Haute disponibilité : Clustering et failover automatique
Flexibilité : Patterns multiples (pub/sub, req/reply, queue groups)

🏗️ Architecture de communication

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ Web Client  │  │ Mobile App  │  │ API Client  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ HTTP/REST
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     API GATEWAY                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Gateway API (NestJS)                      │   │
│  │  • NATS Client Integration                             │   │
│  │  • Request Transformation                              │   │
│  │  • Response Aggregation                                │   │
│  │  • Error Handling                                      │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ NATS Messages
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      NATS SERVER                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Message Broker                       │   │
│  │  • Subject-based Routing                               │   │
│  │  • Queue Groups                                        │   │
│  │  • Load Balancing                                      │   │
│  │  • Message Persistence                                 │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────┼───────────┐
                    │           │           │
                    ▼           ▼           ▼
        ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
        │Auth Service │ │Admin Service│ │TradeFlow Svc│
        │             │ │             │ │             │
        └─────────────┘ └─────────────┘ └─────────────┘

📨 Patterns de communication

1. Request-Response Pattern

Usage : Communication synchrone entre services

// Gateway → Auth Service
const response = await natsClient.send('auth.validate', { 
  token: 'jwt-token-here' 
});

// Auth Service response
{
  success: true,
  result: {
    isValid: true,
    user: {
      id: 123,
      username: 'john.doe',
      role_id: 4
    }
  }
}

Exemples d'utilisation :

Validation des tokens JWT
Récupération des données utilisateur
Validation des permissions
Requêtes de données de référence

Usage : Notifications et événements asynchrones

// Publication d'un événement
natsClient.emit('tradeflow.collection.created', {
  collectionId: 123,
  collectorId: 456,
  timestamp: new Date().toISOString()
});

// Souscription à l'événement
natsClient.subscribe('tradeflow.collection.created', (data) => {
  console.log('Nouvelle collection créée:', data);
  // Traitement asynchrone
});

Exemples d'utilisation :

Notifications de création/modification de collections
Événements d'audit
Mises à jour de cache
Notifications système

3. Queue Groups Pattern

Usage : Traitement distribué et load balancing

// Service A - Producteur
natsClient.emit('tradeflow.validation.queue', {
  collectionId: 123,
  validationLevel: 1
});

// Service B - Consommateur (Worker 1)
natsClient.subscribe('tradeflow.validation.queue', 
  { queue: 'validation-workers' }, 
  (data) => {
    console.log('Worker 1 traite:', data);
  }
);

// Service C - Consommateur (Worker 2)
natsClient.subscribe('tradeflow.validation.queue', 
  { queue: 'validation-workers' }, 
  (data) => {
    console.log('Worker 2 traite:', data);
  }
);

Exemples d'utilisation :

Traitement des validations
Génération de rapports
Envoi d'emails
Traitement des fichiers

🎯 Sujets NATS (Subjects)

Convention de nommage

<service>.<module>.<action>

Sujets par service

Auth Service

'auth.login'              // Connexion utilisateur
'auth.logout'             // Déconnexion
'auth.validate'           // Validation token
'auth.refresh'            // Rafraîchissement token
'auth.profile'            // Profil utilisateur
'auth.permissions'        // Vérification permissions

Admin Service

'admin.users.create'      // Créer utilisateur
'admin.users.update'      // Modifier utilisateur
'admin.users.delete'      // Supprimer utilisateur
'admin.users.list'        // Lister utilisateurs
'admin.roles.manage'      // Gestion des rôles
'admin.actors.create'     // Créer acteur
'admin.actors.update'     // Modifier acteur
'admin.config.update'     // Configuration système

TradeFlow Service

'tradeflow.collections.create'     // Créer collection
'tradeflow.collections.update'     // Modifier collection
'tradeflow.collections.delete'     // Supprimer collection
'tradeflow.collections.get'        // Récupérer collection
'tradeflow.collections.list'       // Lister collections
'tradeflow.validation.submit'      // Soumettre validation
'tradeflow.validation.approve'     // Approuver validation
'tradeflow.validation.reject'      // Rejeter validation
'tradeflow.reports.generate'       // Générer rapport
'tradeflow.statistics.calculate'   // Calculer statistiques

Model Service

'model.definitions.get'    // Récupérer définitions
'model.definitions.create' // Créer définition
'model.types.list'         // Lister types
'model.schemas.validate'   // Valider schéma
'model.metadata.get'       // Récupérer métadonnées

Common Data

'common.countries'         // Données pays
'common.currencies'        // Données devises
'common.products'          // Données produits
'common.animals'           // Données animaux
'common.transport.modes'   // Modes de transport
'common.geo.regions'       // Régions géographiques

🔄 Flux de communication

Flux d'authentification

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant A as Auth Service
    participant D as Database
    
    C->>G: POST /auth/login {username, password}
    G->>A: nats.send('auth.login', {username, password})
    A->>D: SELECT user WHERE username = ?
    D-->>A: User data
    A->>A: bcrypt.compare(password, hash)
    A->>A: Generate JWT token
    A-->>G: {token, user, expires_in}
    G-->>C: Authentication success

Flux de création de collection

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant T as TradeFlow Service
    participant A as Auth Service
    participant D as Database
    
    C->>G: POST /trade-flow/collections {data}
    G->>A: nats.send('auth.validate', {token})
    A-->>G: {isValid: true, user: {...}}
    G->>T: nats.send('tradeflow.collections.create', {data, user})
    T->>D: INSERT INTO collections ...
    D-->>T: {id: 123, public_id: 'uuid'}
    T-->>G: {success: true, result: collection}
    T->>T: nats.emit('tradeflow.collection.created', {collectionId})
    G-->>C: Collection created

Flux de validation multi-niveaux

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant T as TradeFlow Service
    participant D as Database
    
    C->>G: POST /trade-flow/collections/123/validate
    G->>T: nats.send('tradeflow.validation.submit', {collectionId: 123})
    T->>D: UPDATE collections SET status = 'pending_validation'
    T->>T: nats.emit('tradeflow.validation.queue', {collectionId, level: 1})
    T-->>G: {success: true, message: 'Submitted for validation'}
    G-->>C: Validation submitted
    
    Note over T: Validation Worker
    T->>D: SELECT collection WHERE id = 123
    T->>T: Process validation logic
    T->>D: UPDATE collections SET status = 'validated'
    T->>T: nats.emit('tradeflow.validation.completed', {collectionId})

🛠️ Configuration NATS

Configuration du client

// Configuration dans chaque service
import { ClientProxy, ClientProxyFactory, Transport } from '@nestjs/microservices';

const natsClient = ClientProxyFactory.create({
  transport: Transport.NATS,
  options: {
    servers: process.env.NATS_URLS?.split(',') || ['nats://localhost:4222'],
    reconnect: true,
    maxReconnectAttempts: 10,
    reconnectTimeWait: 2000,
    timeout: 5000,
    maxPayload: 1024 * 1024, // 1MB
    name: 'commerce-tracking-service',
    user: process.env.NATS_USER,
    pass: process.env.NATS_PASS,
  },
});

Configuration du serveur

# nats-server.conf
port: 4222
http_port: 8222

# Clustering (pour haute disponibilité)
cluster {
  port: 6222
  routes: [
    "nats://nats-1:6222"
    "nats://nats-2:6222"
    "nats://nats-3:6222"
  ]
}

# Persistance
jetstream {
  store_dir: "/data/jetstream"
  max_memory_store: 2GB
  max_file_store: 10GB
}

# Monitoring
monitor_port: 8222

🔧 Gestion des erreurs

Timeout et retry

// Configuration du timeout
const response = await natsClient.send('auth.validate', { token }, { 
  timeout: 5000 // 5 secondes
});

// Gestion des erreurs avec retry
async function sendWithRetry(subject: string, data: any, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await natsClient.send(subject, data, { timeout: 5000 });
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      console.log(`Tentative ${i + 1} échouée, retry dans ${1000 * (i + 1)}ms`);
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Circuit breaker

class CircuitBreaker {
  private failures = 0;
  private lastFailureTime = 0;
  private readonly threshold = 5;
  private readonly timeout = 60000; // 1 minute

  async call(subject: string, data: any) {
    if (this.isOpen()) {
      throw new Error('Circuit breaker is open');
    }

    try {
      const result = await natsClient.send(subject, data);
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private isOpen(): boolean {
    return this.failures >= this.threshold && 
           (Date.now() - this.lastFailureTime) < this.timeout;
  }

  private onSuccess() {
    this.failures = 0;
  }

  private onFailure() {
    this.failures++;
    this.lastFailureTime = Date.now();
  }
}

📊 Monitoring et observabilité

Métriques NATS

// Métriques de performance
const metrics = {
  messagesSent: 0,
  messagesReceived: 0,
  errors: 0,
  averageLatency: 0,
  connections: 0
};

// Middleware de monitoring
natsClient.subscribe('*', (data, subject) => {
  metrics.messagesReceived++;
  console.log(`Message reçu sur ${subject}:`, data);
});

Health checks

// Health check NATS
async function checkNatsHealth(): Promise<boolean> {
  try {
    await natsClient.send('health.ping', {}, { timeout: 1000 });
    return true;
  } catch (error) {
    console.error('NATS health check failed:', error);
    return false;
  }
}

Cette architecture de communication basée sur NATS garantit la scalabilité, la résilience et la performance du système Commerce Tracking. Les patterns utilisés permettent une évolution flexible et une maintenance simplifiée.

🎯 Vue d'ensemble​

Avantages de NATS​

🏗️ Architecture de communication​

📨 Patterns de communication​

1. Request-Response Pattern​

2. Publish-Subscribe Pattern​

3. Queue Groups Pattern​

🎯 Sujets NATS (Subjects)​

Convention de nommage​

Sujets par service​

Auth Service​

Admin Service​

TradeFlow Service​

Model Service​

Common Data​

🔄 Flux de communication​

Flux d'authentification​

Flux de création de collection​

Flux de validation multi-niveaux​

🛠️ Configuration NATS​

Configuration du client​

Configuration du serveur​

🔧 Gestion des erreurs​

Timeout et retry​

Circuit breaker​

📊 Monitoring et observabilité​

Métriques NATS​

Health checks​

🎯 Vue d'ensemble

Avantages de NATS

🏗️ Architecture de communication

📨 Patterns de communication

1. Request-Response Pattern

2. Publish-Subscribe Pattern

3. Queue Groups Pattern

🎯 Sujets NATS (Subjects)

Convention de nommage

Sujets par service

Auth Service

Admin Service

TradeFlow Service

Model Service

Common Data

🔄 Flux de communication

Flux d'authentification

Flux de création de collection

Flux de validation multi-niveaux

🛠️ Configuration NATS

Configuration du client

Configuration du serveur

🔧 Gestion des erreurs

Timeout et retry

Circuit breaker

📊 Monitoring et observabilité

Métriques NATS

Health checks