Documentation Technique

Architecture et Implémentation - Burida API

🏗️ Architecture Technique

Stack Technologique

Framework: Quarkus 3.26.2
Framework Java natif cloud supersonic subatomic
Langage: Java 21 LTS
Version LTS avec virtual threads
Base de données: PostgreSQL 12+
SGBDR robuste et performant
ORM: Hibernate ORM + Panache
Simplification de la persistance
Cache: Redis / Caffeine
Cache distribué et local
Monitoring: Micrometer + Prometheus
Métriques et observabilité

Architecture en Couches

API REST
JAX-RS / RESTEasy
→
Services
Logique métier
→
Repository
Panache JPA
→
Database
PostgreSQL

🔐 Sécurité

Authentification HMAC-SHA256

L'API utilise une authentification basée sur HMAC-SHA256 avec plusieurs stratégies de signature :

Stratégie Description Cas d'usage
FIELDS Signature des champs critiques uniquement Recommandé pour les partenaires Mobile Money
HASH Signature du hash SHA-256 du body Bon compromis performance/sécurité
SIMPLIFIED Signature sans body Requêtes GET
CHECKSUM Signature avec CRC32 du body Vérification rapide

Exemple de Génération de Signature

SECRET

secretKey: ${HMAC_SECRET}  // Valeur fournie par l'administrateur (variable d'environnement)

METHOD : POST

// Stratégie FIELDS - Recommandée
String method = "POST";
String path = "/api/webhook/orange/paiement";
String timestamp = String.valueOf(Instant.now().getEpochSecond());

// Construire la chaîne à signer avec les champs critiques
String dataToSign = method + "|" + path + "|" + timestamp + 
                    "|idTransaction=" + transaction.getId();

// Calculer HMAC-SHA256
SecretKeySpec secretKey = new SecretKeySpec(
    secret.getBytes(StandardCharsets.UTF_8), 
    "HmacSHA256"
);
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(secretKey);
byte[] hmacBytes = mac.doFinal(dataToSign.getBytes(StandardCharsets.UTF_8));
String signature = Base64.getEncoder().encodeToString(hmacBytes);

METHOD : GET

// Stratégie FIELDS - Recommandée
String method = "GET";
String path = "/api/{{codeMobile}}/factures-non-soldees";
String timestamp = String.valueOf(Instant.now().getEpochSecond());

// Construire la chaîne à signer avec les champs critiques
String dataToSign = method + "|" + path + "|" + timestamp;

// Calculer HMAC-SHA256
SecretKeySpec secretKey = new SecretKeySpec(
    secret.getBytes(StandardCharsets.UTF_8),
    "HmacSHA256"
);
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(secretKey);
byte[] hmacBytes = mac.doFinal(dataToSign.getBytes(StandardCharsets.UTF_8));
String signature = Base64.getEncoder().encodeToString(hmacBytes);

⚡ Performance & Optimisation

Configuration des Pools de Connexions

Environnement Min Pool Max Pool Timeout
DEV 5 20 30s
HOMO 10 30 30s
PROD 50 200 10s

Rate Limiting

Limites configurées par environnement (requêtes/minute) :

Type DEV HOMO PROD IPs partenaires prioritaires
Consultations 100 500 5,000 50,000
Webhooks 200 1,000 10,000
Défaut 150 750 7,500

📊 Modèle de Données

Entités Principales

Client
• codeClient (PK)
• nom, prenom
• telephone, email
• adresse
Facture
• idFacture (PK)
• numeroFacture
• montant, statut
• dateEmission
• client (FK)
Paiement
• idTransaction (PK)
• montant, devise
• dateTransaction
• statut
• facture (FK)
WebhookRequest
• id (PK)
• requestBody
• responseStatus
• timestamp
• retryCount

Relations

Client (1) ←→ (N) Facture
Client (1) ←→ (N) Contrat
Facture (1) ←→ (N) Paiement
Contrat (1) ←→ (N) Facture
WebhookRequest (1) ←→ (1) Paiement

🚀 Déploiement

Build & Packaging

# Build standard JVM
./mvnw clean package

# Build natif GraalVM
./mvnw package -Pnative

# Build Docker
docker build -f src/main/docker/Dockerfile.jvm -t burida-api .

# Build Docker natif
docker build -f src/main/docker/Dockerfile.native -t burida-api:native .

Configuration par Environnement

L'application utilise des profils Quarkus pour gérer les configurations :

Variables d'Environnement

# Base de données
DB_PASSWORD=your-secure-password

# HMAC Secret
HMAC_SECRET=your-256-bit-secret-key

# Redis (Production)
REDIS_HOST=redis-server.domain.com
REDIS_PORT=6379

# Profil actif
QUARKUS_PROFILE=prod

🔧 Maintenance & Monitoring

Endpoints de Monitoring

Endpoint Description Auth
/q/health État général de l'application Non
/q/health/live Liveness probe Kubernetes Non
/q/health/ready Readiness probe Kubernetes Non
/q/metrics Métriques Prometheus Basic Auth

Logs & Debugging

Configuration des niveaux de logs par package :

quarkus.log.level=INFO
quarkus.log.category."com.ebenyx.burida".level=DEBUG
quarkus.log.category."com.ebenyx.burida.security".level=INFO
quarkus.log.category."org.hibernate.SQL".level=DEBUG
← Retour