Schéma Technique
Flux de Données

1.1 Objectif du Document

Ce document décrit en détail les flux de données circulant au sein de l'écosystème REWAPP. Il présente les interactions entre les différents services, les protocoles de communication utilisés, et les mécanismes de sécurité appliqués à chaque flux.

1.2 Composants Principaux

L'écosystème REWAPP comprend les composants suivants qui échangent des données :

1.3 Principes de Conception des Flux

• API-First Toute communication passe par des APIs REST standardisées (OpenAPI 3.0)
• Stateless Aucune session serveur, authentification via JWT pour scalabilité horizontale
• Event-Driven Communication asynchrone entre services via Bull Queue (Redis)
• Security by Design Chiffrement TLS 1.3, signature des données sensibles
• Idempotence Les opérations critiques sont idempotentes pour éviter les doublons

2.1 Vue Globale de l'Architecture

2.2 Patterns de Communication

2.3 Formats de Données

Toutes les données échangées utilisent le format JSON avec les conventions suivantes :

• Nommage : camelCase pour les propriétés
• Dates : Format ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ)
• Identifiants : UUID v4 non séquentiels
• Montants : Entiers (cents pour euros, unités pour points)
• Encodage : UTF-8

3.1 Flux Client vers API Gateway

Les applications clientes communiquent avec l'API Gateway via HTTPS (TLS 1.3). Chaque requête authentifiée inclut un token JWT dans le header Authorization.

3.2 Flux API Gateway vers Microservices

L'API Gateway route les requêtes vers le microservice approprié en fonction du path URL.

3.3 Flux Inter-Services Synchrones

Certains microservices communiquent entre eux de manière synchrone pour des opérations nécessitant une réponse immédiate.

4.1 Architecture Bull Queue

Les flux asynchrones utilisent Bull Queue (basé sur Redis) pour le traitement en arrière-plan et la communication inter-services découplée.

4.2 Événements Principaux

4.3 Configuration des Jobs

5.1 Flux d'Inscription Utilisateur

5.2 Flux de Liaison Carte Bancaire (Card Linking)

5.3 Flux de Détection Transaction et Crédit Points

5.4 Flux de Génération QR Code

5.5 Flux de Scan QR Code et Débit Points

5.6 Flux de Demande de Virement Bancaire

6.1 Diagramme Global - Architecture des Flux

@startuml
skinparam backgroundColor #FFFFFF
skinparam componentStyle rectangle
skinparam roundcorner 10

title Architecture Globale des Flux de Donnees REWAPP

rectangle "Applications Clientes" as clients #LightBlue {
  [App Mobile] as mobile #LightGreen
  [Site Vitrine] as vitrine #LightCyan
  [Dashboard Admin] as admin #Yellow
  [Dashboard Partenaire] as partner #Orange
}

cloud "API Gateway" as gateway #Gold {
  [Kong / Traefik Gateway] as kong #Orange
}

rectangle "Microservices" as services #LightGreen {
  [Auth Service] as auth #LightCyan
  [User Service] as user #LightYellow
  [Transaction Service] as transaction #Pink
  [Points Service] as points #Plum
  [QR Code Service] as qrcode #Coral
  [Merchant Service] as merchant #LightGray
  [Banking Service] as banking #Yellow
  [Notification Service] as notif #Aqua
  [Admin Service] as adminSvc #Lavender
}

database "Data Layer" as data #LightGray {
  [PostgreSQL] as pg #Pink
  [Redis] as redis #Salmon
}

rectangle "Services Externes" as external #LightCoral {
  [Budget Insight] as bi #LightGreen
  [Firebase FCM] as fcm #Orange
  [SendGrid] as sg #Yellow
}

mobile --> kong : HTTPS REST
vitrine --> kong : HTTPS REST
admin --> kong : HTTPS REST
partner --> kong : HTTPS REST

kong --> auth
kong --> user
kong --> transaction
kong --> points

auth --> pg
user --> pg
transaction --> pg
points --> pg

auth --> redis
points --> redis
qrcode --> redis

banking --> bi
notif --> fcm
notif --> sg

bi --> banking : Webhooks

@enduml

6.2 Diagramme de Séquence - Flux Transaction Complète

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowThickness 2
skinparam roundcorner 10

title Flux Achat Detection Credit Points

actor Client #LightBlue
participant "App Mobile" as app #LightGreen
participant "Commercant" as shop #Orange
participant "Budget Insight" as bi #Cyan
participant "API Gateway" as gw #Yellow
participant "Transaction Service" as tx #Pink
participant "Points Service" as pts #Plum
participant "Notification" as notif #Coral
database "PostgreSQL" as pg #LightGray
database "Redis Queue" as redis #Salmon

Client -> shop : Paiement carte bancaire
shop -> bi : Transaction remontee
bi -> gw : POST /webhooks/banking
gw -> tx : Forward webhook
tx -> tx : Validation signature HMAC
tx -> pg : SELECT merchant MCC
tx -> tx : Calcul cashback
tx -> pg : INSERT transaction
tx -> redis : Event transaction detected
redis -> pts : Consume event
pts -> pg : INSERT points_ledger CREDIT
pts -> redis : Event points credited
redis -> notif : Consume event
notif -> app : Push notification +15 points
app -> Client : Affichage notification

@enduml

6.3 Diagramme de Séquence - Flux QR Code Complet

@startuml
skinparam backgroundColor #FFFFFF
skinparam sequenceArrowThickness 2
skinparam roundcorner 10

title Flux Generation Scan Debit QR Code

actor Client #LightBlue
actor Partenaire #Orange
participant "App Mobile" as app #LightGreen
participant "Dashboard" as dash #Yellow
participant "API Gateway" as gw #Gold
participant "QR Service" as qr #Pink
participant "Points Service" as pts #Plum
participant "Notification" as notif #Coral
database "Redis" as redis #Salmon
database "PostgreSQL" as pg #LightGray

Client -> app : Genere QR 500 points
app -> gw : POST /qr-codes/generate
gw -> qr : Forward request
qr -> pts : GET solde disponible
pts -> pg : SELECT balance
pts --> qr : balance 2450 pts
qr -> redis : SETEX locked 60s
qr -> qr : Genere QR signature HMAC
qr -> redis : SETEX qr 60s
qr --> app : qrCodeImage expiresAt

Client -> Partenaire : Presente QR code
Partenaire -> dash : Scan QR code
dash -> gw : POST /qr-codes/scan
gw -> qr : Forward scan
qr -> redis : GET qr
qr -> qr : Verification signature
qr -> qr : Verification expiration
qr -> redis : SETNX used
qr -> pts : Debit 500 points
pts -> pg : INSERT points_ledger DEBIT
pts -> redis : DEL locked
qr -> redis : Event qr_code scanned
redis -> notif : Consume event
notif -> app : Push Paiement valide
notif -> dash : WebSocket confirmation
dash -> Partenaire : Affichage validation

@enduml

6.4 Diagramme de Flux de Données - Vue DFD Niveau 1

@startuml
skinparam backgroundColor #FFFFFF
skinparam roundcorner 10

title DFD Niveau 1 - Flux de Donnees REWAPP

rectangle "Entites Externes" #LightBlue {
  actor "Utilisateur Mobile" as user #LightGreen
  actor "Commercant Partenaire" as merchant #Orange
  actor "Administrateur" as admin #Yellow
  entity "Solution Bancaire" as bank #Cyan
}

rectangle "Processus REWAPP" #LightGreen {
  usecase "P1 Authentification" as p1 #LightCyan
  usecase "P2 Profil" as p2 #LightYellow
  usecase "P3 Transactions" as p3 #Pink
  usecase "P4 Points" as p4 #Plum
  usecase "P5 QR Codes" as p5 #Coral
  usecase "P6 Virements" as p6 #LightGray
  usecase "P7 Partenaires" as p7 #Aqua
  usecase "P8 Notifications" as p8 #Lavender
}

database "Stockages" #LightGray {
  storage "D1 Users" as d1 #Pink
  storage "D2 Transactions" as d2 #Salmon
  storage "D3 Points Ledger" as d3 #Plum
  storage "D4 QR Codes" as d4 #Coral
  storage "D5 Merchants" as d5 #Aqua
  storage "D6 Withdrawals" as d6 #Yellow
}

user --> p1 : Credentials
p1 --> user : JWT Tokens
p1 --> d1 : RW User

user --> p2 : Profile data
p2 --> d1 : RW User

bank --> p3 : Webhook transaction
p3 --> d2 : W Transaction
p3 --> p4 : Transaction detectee

p4 --> d3 : RW Points
p4 --> p8 : Points credites
p8 --> user : Push notification

user --> p5 : Demande QR
p5 --> d4 : W QR Code
p5 --> p4 : Blocage points
p5 --> user : QR Code image

merchant --> p5 : Scan QR
p5 --> p4 : Debit points
p5 --> p8 : Scan valide
p8 --> merchant : Confirmation

admin --> p7 : Validation
p7 --> d5 : RW Merchant
p7 --> p8 : Partenaire valide
p8 --> merchant : Notification

@enduml

7.1 Chiffrement des Données en Transit

7.2 Authentification des Flux

7.3 Validation des Données

7.4 Protection des Données Sensibles

8.1 Stratégie de Retry

8.2 Dead Letter Queue (DLQ)

Les messages en échec après toutes les tentatives sont placés dans une Dead Letter Queue pour analyse :

• Stockage : Queue Redis dédiée (dlq:{queue_name})
• Rétention : 7 jours
• Alerting : Notification Slack si DLQ > 100 messages
• Replay : Possibilité de rejouer manuellement les messages

8.3 Circuit Breaker

8.4 Idempotence

Toutes les opérations critiques sont idempotentes grâce à des identifiants uniques :

• Transactions : transactionId unique (UUID fourni par le webhook)
• Points : Clé composite (userId, transactionId, type)
• QR Codes : qrCodeId unique avec flag "used" atomique
• Virements : withdrawalId avec vérification statut préalable

9.1 Métriques de Flux

9.2 Tracing Distribué

Chaque requête est tracée à travers tous les services avec un identifiant unique :

• Request ID : UUID généré par l'API Gateway
• Trace ID : Propagé dans les headers (X-Request-ID)
• Span ID : Identifiant de chaque opération
• Corrélation : Logs enrichis avec requestId pour suivi end-to-end

9.3 Logs des Flux

9.4 Dashboards de Monitoring

10.1 Récapitulatif des Flux

L'architecture de flux de données REWAPP repose sur une combinaison équilibrée de communications synchrones et asynchrones :

• Flux synchrones : Opérations utilisateur nécessitant une réponse immédiate (< 200ms)
• Flux asynchrones : Traitements en arrière-plan, notifications, calculs différés
• Webhooks : Intégration avec les partenaires externes (solution bancaire)
• WebSocket : Communications temps réel (scan QR, notifications dashboard)

10.2 Points Clés de l'Architecture

• Découplage Les services communiquent via API et events, permettant une évolution indépendante
• Résilience Retry automatique, circuit breakers, dead letter queues
• Scalabilité Architecture stateless, queues distribuées, auto-scaling
• Sécurité Chiffrement bout-en-bout, authentification JWT, signatures HMAC
• Observabilité Tracing distribué, métriques temps réel, alerting proactif

10.3 Références Complémentaires