Architecture Backend API

1.1 Principes Architecturaux

• Microservices

  Séparation des domaines fonctionnels en services indépendants et autonomes

• API-First

  Toute communication passe par des APIs REST standardisées suivant 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

  Sécurité intégrée dès la conception à tous les niveaux

• Cloud Native

  Optimisation pour infrastructure AWS avec containers Docker

1.2 Stack Technique Backend

1.3 Composants Principaux

• API Gateway : Point d'entrée unique pour toutes les requêtes clients
• Services Métier : Microservices NestJS spécialisés par domaine fonctionnel
• Bull Queue : Traitement asynchrone des jobs (notifications, calculs, virements)
• Redis : Cache distribué et gestion des sessions
• PostgreSQL : Stockage persistant des données transactionnelles
• S3 : Stockage des fichiers et médias

2.1 Service Authentification (Auth Service)

2.1.1 Endpoints Principaux

2.1.2 Sécurité Authentification

• Access Token : Validité 15 minutes, signature RS256
• Refresh Token : Validité 7 jours, stocké hashé en base
• Mots de passe : Hashage bcrypt (10 rounds minimum)
• Protection brute force : 5 tentatives max par IP/email sur 15 minutes
• Device fingerprinting : Détection des nouveaux appareils

2.2 Service Utilisateurs (User Service)

2.2.1 Endpoints Principaux

2.3 Service Transactions (Transaction Service)

2.3.1 Intégration OpenBanking

Le service s'intègre avec les fournisseurs OpenBanking (Budget Insight recommandé, Plaid, Tink) pour la détection automatique des transactions. L'intégration respecte la norme PSD2.

2.3.2 Endpoints Principaux

2.4 Service Points et Fidélité (Points Service)

2.4.1 Règles Métier Implémentées

2.4.2 Endpoints Principaux

2.4.3 Calcul des Paliers

Le palier est recalculé quotidiennement (job Bull Queue à 2h00) :

• Calcul par partenaire sur les 12 derniers mois glissants
• Bonus cashback : Bronze +0%, Silver +5%, Gold +10%, Platine +15%, Diamant +20%

2.5 Service QR Codes (QR Code Service)

2.5.1 Règles de Sécurité QR Code

2.5.2 Génération du QR Code

Contenu du QR Code (JSON signé) :

• ID utilisateur (chiffré)
• Montant en points
• Montant en euros (points × 0,105)
• Timestamp de génération (Unix ms)
• ID transaction unique (UUID)
• Signature HMAC-SHA256

2.5.3 Endpoints Principaux

2.5.4 Flux de Paiement QR

2.6 Service Partenaires (Merchant Service)

2.6.1 Statuts Partenaires

• pending : En attente de validation admin (OBLIGATOIRE)
• approved : Validé et actif
• rejected : Refusé avec motif
• suspended : Suspendu temporairement
• inactive : Désactivé par le partenaire

2.6.2 Endpoints API Publique

2.6.3 Endpoints Dashboard Partenaire

2.7 Service Bancaire (Banking Service)

2.7.1 Card Linking

Intégration OpenBanking pour liaison sécurisée :

• OAuth 2.0 pour autorisation utilisateur
• Tokenisation PCI DSS (aucun numéro de carte stocké)
• Webhook pour nouvelles transactions

2.7.2 Endpoints Principaux

2.7.3 Statuts de Virement

• pending : En attente, annulation possible
• processing : En cours de traitement, annulation impossible
• completed : Virement effectué
• failed : Échec (motif fourni)
• cancelled : Annulé par l'utilisateur

2.8 Service Notifications (Notification Service)

2.8.1 Types de Notifications

• points_credited : Points crédités suite à transaction
• qr_payment_success : Paiement QR validé
• withdrawal_completed : Virement effectué
• tier_upgrade : Passage au palier supérieur
• points_expiring : Points sur le point d'expirer (J-30, J-7)
• promotion : Offre promotionnelle partenaire

2.8.2 Endpoints Principaux

2.9 Service Administration (Admin Service)

2.9.1 Endpoints Admin (Rôle Admin requis)

3.1 Architecture Kong Gateway

L'API Gateway Kong centralise toutes les requêtes entrantes et fournit les fonctionnalités transversales.

3.1.1 Fonctionnalités Principales

• Rate Limiting - Protection contre les abus et surcharges
• Authentication - Validation des tokens JWT
• Load Balancing - Répartition de charge entre instances
• Request/Response Transform - Transformation et validation des données
• Logging - Centralisation des logs vers ELK Stack
• Circuit Breaker - Protection contre les cascades de pannes

3.2 Configuration du Rate Limiting

3.3 Routage des Services

3.4 Health Checks

Chaque microservice expose un endpoint /health vérifié toutes les 30 secondes par l'API Gateway :

• Statut de la connexion PostgreSQL
• Statut de la connexion Redis
• Métriques de latence interne

4.1 Communication Synchrone (REST)

Pour les opérations nécessitant une réponse immédiate :

• Format : REST JSON via HTTP/HTTPS
• Timeout : 5 secondes par défaut
• Retry : 3 tentatives avec exponential backoff (1s, 2s, 4s)
• Auth : Service tokens JWT distincts des tokens utilisateurs

4.2 Communication Asynchrone (Bull Queue)

Pour les opérations non critiques et le traitement en arrière-plan :

4.2.1 Queues Principales

4.2.2 Événements Principaux

• user.registered : Déclenchement email de bienvenue
• transaction.detected : Calcul et crédit des points
• points.credited : Notification push utilisateur
• qr_code.scanned : Débit points + notification
• withdrawal.requested : Initiation du virement
• tier.upgraded : Notification félicitations

4.2.3 Gestion des Erreurs

• Retry automatique : 3 tentatives avec backoff
• Dead Letter Queue : Messages en échec stockés pour analyse
• Alerting : Notification Slack si DLQ > 100 messages

5.1 PostgreSQL (Base Principale)

5.1.1 Configuration

• Version : PostgreSQL 15+
• Extensions : UUID-OSSP, PostGIS (géolocalisation)
• Réplication : Master-Slave pour haute disponibilité
• Backup : Quotidien avec rétention 30 jours
• Connection Pool : PgBouncer (max 100 connexions)

5.1.2 Tables Principales

5.2 Redis (Cache & Sessions)

5.2.1 Utilisation

• Sessions JWT : TTL 24 heures
• Cache API : TTL variable selon endpoint
• QR codes actifs : TTL 60 secondes
• Rate limiting : Compteurs par IP/utilisateur
• Bull Queue : Stockage des jobs

5.2.2 Configuration

• Mode : Cluster pour haute disponibilité
• Réplication : Master avec 2 replicas
• Mémoire : 2GB minimum production

6.1 Format Standard des Erreurs

Toutes les réponses d'erreur suivent un format JSON standardisé :

{
  "success": false,
  "error": {
    "code": "ERR_INVALID_CREDENTIALS",
    "message": "Email ou mot de passe incorrect",
    "details": [],
    "timestamp": "2025-11-24T10:30:00.000Z",
    "traceId": "abc123-def456-ghi789",
    "path": "/api/v1/auth/login"
  }
}

6.2 Codes HTTP Standardisés

6.2.1 Codes de Succès (2xx)

6.2.2 Codes d'Erreur Client (4xx)

6.2.3 Codes d'Erreur Serveur (5xx)

6.3 Codes d'Erreur Métier REWAPP

6.3.1 Erreurs Authentification (AUTH_)

• AUTH_INVALID_CREDENTIALS : Identifiants incorrects
• AUTH_ACCOUNT_LOCKED : Compte verrouillé (trop de tentatives)
• AUTH_ACCOUNT_NOT_VERIFIED : Email non vérifié
• AUTH_TOKEN_EXPIRED : Token JWT expiré
• AUTH_TOKEN_INVALID : Token JWT invalide
• AUTH_BIOMETRIC_FAILED : Authentification biométrique échouée

6.3.2 Erreurs Points (POINTS_)

• POINTS_INSUFFICIENT_BALANCE : Solde de points insuffisant
• POINTS_AMOUNT_TOO_LOW : Montant inférieur au minimum (10 points)
• POINTS_ALREADY_REDEEMED : Points déjà utilisés
• POINTS_EXPIRED : Points expirés
• POINTS_BLOCKED : Points bloqués (virement en cours)

6.3.3 Erreurs QR Code (QR_)

• QR_INVALID : QR code invalide ou malformé
• QR_EXPIRED : QR code expiré (durée de vie 60s)
• QR_ALREADY_USED : QR code déjà scanné
• QR_SIGNATURE_INVALID : Signature cryptographique invalide

6.3.4 Erreurs Bancaires (BANK_)

• BANK_CARD_LINKING_FAILED : Liaison carte échouée
• BANK_CARD_ALREADY_LINKED : Carte déjà liée
• BANK_IBAN_INVALID : IBAN invalide
• BANK_WITHDRAWAL_PENDING : Virement déjà en cours
• BANK_WITHDRAWAL_MINIMUM : Minimum 100 points non atteint

7.1 Structure des Réponses

7.1.1 Réponse de Succès Simple

{
  "success": true,
  "data": {
    "id": "user_abc123",
    "email": "jean.dupont@example.com",
    "firstName": "Jean",
    "lastName": "Dupont"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-11-24T10:30:00.000Z"
  }
}

7.1.2 Réponse de Liste Paginée

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

7.2 Exemples de Réponses

{
  "success": true,
  "data": {
    "available": 2450,
    "pending": 150,
    "blocked": 0,
    "total": 2600,
    "equivalentEuros": {
      "bankCashback": 232.75,
      "merchantCashback": 257.25
    },
    "expiringPoints": {
      "amount": 500,
      "expiresAt": "2025-12-31T23:59:59.000Z"
    }
  }
}

{
  "success": true,
  "data": {
    "qrCodeId": "qr_xyz789",
    "qrCodeData": "REWAPP:PAY:qr_xyz789:500:sig_abc123",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
    "pointsAmount": 500,
    "euroAmount": 52.50,
    "expiresAt": "2025-11-24T10:31:00.000Z",
    "validitySeconds": 60,
    "status": "ACTIVE"
  }
}

7.3 Pagination

7.3.1 Paramètres de Requête

• page : Numéro de page (défaut: 1)
• limit : Éléments par page (défaut: 20, max: 100)
• sort : Champ de tri (ex: createdAt)
• order : Ordre (asc ou desc)

8.1 Stratégie de Versioning

L'API REWAPP utilise le versioning dans l'URL : /api/v{major}/

8.2 Règles de Versioning

• Versions mineures : Pas de nouvelle URL (rétrocompatibles)
• Ajout de champs : Rétrocompatible, pas de nouvelle version
• Suppression de champs : Nouvelle version majeure requise
• Support minimum : 12 mois après sortie de la version suivante

8.3 Politique de Déprécation

Headers de déprécation ajoutés aux réponses :

• Deprecation: true
• Sunset: Sat, 24 Nov 2026 23:59:59 GMT
• X-API-Warn: Message d'avertissement

9.1 Authentification JWT

9.1.1 Architecture

• Access Token : 15 minutes, signature RS256
• Refresh Token : 7 jours, hashé en base
• Rotation des clés : Tous les 90 jours
• JWKS endpoint : https://api.rewapp.fr/.well-known/jwks.json

9.1.2 Structure du JWT

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key_2025_v1"
}

{
  "sub": "user_abc123",
  "email": "jean.dupont@example.com",
  "role": "USER",
  "permissions": ["read:points", "write:qrcode"],
  "deviceId": "device_xyz789",
  "iat": 1732441800,
  "exp": 1732442700,
  "iss": "https://api.rewapp.fr",
  "aud": "rewapp-mobile"
}

9.2 Protection des Données

9.3 Protection contre les Attaques

9.3.1 Protection OWASP Top 10

• SQL Injection : Requêtes paramétrées via Prisma ORM
• XSS : Content Security Policy, encodage HTML
• CSRF : Double Submit Cookie, SameSite=Strict
• IDOR : UUID non séquentiels, vérification propriété
• Rate Limiting : Par IP et par utilisateur

9.3.2 Gestion des Secrets

• Variables CapRover : Credentials et API keys
• Rotation automatique : Tous les 90 jours
• Principe du moindre privilège : IAM roles

10.1 Stratégie de Tests

10.2 Standards de Code

• ESLint : Configuration stricte
• Prettier : Formatage automatique
• TypeScript : Mode strict activé
• Husky : Hooks pre-commit (lint + tests)

10.3 Pipeline CI/CD (GitHub Actions)

11.1 Accès à la Documentation

• Swagger UI : https://api.rewapp.fr/docs
• OpenAPI JSON : https://api.rewapp.fr/docs/openapi.json
• ReDoc : https://api.rewapp.fr/redoc

11.2 Organisation par Tags

11.3 Génération de Clients

La spécification OpenAPI permet la génération automatique de clients :

• TypeScript : openapi-typescript-codegen
• Swift (iOS) : OpenAPIGenerator
• Kotlin (Android) : OpenAPIGenerator

12.1 Résumé de l'Architecture

12.2 Design Patterns Adoptés

• Repository Pattern : Abstraction de l'accès aux données
• Service Layer : Logique métier isolée et testable
• DTO Pattern : Contrôle des données exposées
• Factory Pattern : Création d'objets complexes
• Observer Pattern : Événements asynchrones

12.3 Principes SOLID

• Single Responsibility : Un service = une responsabilité
• Open/Closed : Extension sans modification
• Liskov Substitution : Interfaces interchangeables
• Interface Segregation : Interfaces minimalistes
• Dependency Inversion : Injection de dépendances

12.4 Points Clés

• Scalabilité

  Architecture microservices avec auto-scaling horizontal

• Sécurité

  Protection multicouche, conformité RGPD/PCI DSS

• Performance

  Temps de réponse < 200ms, cache multi-niveaux

• Maintenabilité

  Code modulaire, testé et documenté

• Fiabilité

  SLA 99.9%, déploiement multi-AZ, circuit breakers

12.5 Références Complémentaires