Analyse architecturale d'une plateforme e-commerce : le cas d'un SPA React/Vite

Contexte et méthodologie

Cet article propose une analyse technique détaillée d'un site e-commerce existant, identifié comme utilisant une architecture SPA React/Vite, un CDN Cloudflare et une API REST maison. L'objectif est de comprendre les forces et les faiblesses de cette architecture, de la comparer à une solution plus traditionnelle comme WooCommerce, et de proposer une feuille de route pour une réécriture potentielle.

Note importante : Ce qui suit distingue trois types de conclusions : les faits observables (via l'inspection du code et des requêtes réseau), les inférences techniques (sur le fonctionnement probable du backend), et les recommandations (pour une nouvelle architecture). Il n'est pas possible, sans accès aux serveurs, de déterminer le langage backend exact (Node.js, PHP, Python). L'analyse se concentre sur la logique métier et les patterns d'architecture.

1. Architecture actuelle : forces et faiblesses

1.1 Une architecture à trois couches

Le site suit un modèle classique pour les applications modernes :

1. Cloudflare / CDN & Reverse Proxy : Gère la terminaison TLS, sert les assets statiques (JS, CSS, images) et reverse-proxie les requêtes dynamiques vers le serveur d'origine. Cela permet une mise en cache efficace et une distribution mondiale rapide.
2. SPA React (Vite) : L'ensemble de l'interface utilisateur est une application React monopage. Le routage, la gestion d'état et le rendu s'effectuent entièrement dans le navigateur du client.
3. Backend REST : Fournit toutes les données dynamiques : catalogue produits, CMS, sections de page d'accueil, configuration du magasin, gestion des coupons, intégration PayPal, newsletter, avis, etc.

Ce qui distingue ce site d'une solution standard : il ne s'agit pas de WooCommerce, Shopify ou WordPress headless. Les endpoints API, le schéma des produits, et la logique de paiement sont entièrement personnalisés.

1.2 Le flux de chargement initial

Lorsqu'un utilisateur accède à n'importe quelle route (/, /shop, /product/<slug>), le serveur renvoie une coque d'application (app-shell) HTML quasiment vide, qui contient des scripts JavaScript et, potentiellement, des données initiales dans des variables

window.__ ...

1. Le navigateur reçoit l'app-shell.
2. Il charge le bundle JS/CSS (avec hash de contenu pour un cache efficace).
3. React s'initialise et le routeur analyse l'URL pour afficher le bon composant de page.
4. La page récupère les données depuis l'API REST.
5. React construit le DOM et attache les gestionnaires d'événements.
6. Les navigations ultérieures utilisent l'API History du navigateur, évitant un rechargement complet de la page.

Problème potentiel : Cette approche est du rendu 100 % côté client (CSR). La présence de variables window.__ dans l'HTML ne prouve pas un rendu serveur (SSR). Si le contenu (titre, description, prix) n'est pas présent dans l'HTML initial, Googlebot peut avoir des difficultés à l'indexer, même s'il exécute JavaScript . Google recommande l'utilisation de SSR ou de pré-rendu pour le contenu critique .

1.3 Le flux de données du catalogue

Les endpoints d'API révèlent une logique intéressante :

• GET /api/products?limit=500&active=1

  : Récupère tous les produits actifs.

• GET /api/products?q=...

  : Recherche de produits.

• GET /api/products/<slug>

  : Détail d'un produit.

• GET /api/products/categories

  : Catégories.

Ce découplage permet de modifier le catalogue en base de données sans avoir à redéployer le frontend, un avantage majeur. Cependant, l'utilisation de limit=500 pour tout le catalogue est un signal d'alarme. Pour les 16 produits actuels, c'est acceptable. Mais pour un catalogue de plusieurs milliers de SKU, cette approche deviendrait un goulet d'étranglement.

Analyse du schéma produit : Plusieurs incohérences suggèrent un modèle de données qui a évolué au fil du temps sans refactorisation :

• Le stock est géré au niveau du produit, alors que des variants existent. Dans un modèle cohérent, le stock et le SKU devraient être propres à chaque variante (ex : Taille M / Couleur Noir).
• Les tableaux sizes, colors, genders peuvent être redondants avec les données des variantes.
• Des valeurs non normalisées apparaissent (XXL et 2XL,

  ink navy

  et

  Ink Navy

  ), ce qui complique les filtres et l'analytique.
• Les champs image et images ont des rôles qui se chevauchent.

Ces incohérences sont des problèmes techniques qui deviendront critiques à mesure que le catalogue grandit.

1.4 Homepage Builder : Flexible mais fragile

Le système de page d'accueil semble être un constructeur piloté par les données. Des champs comme section_order et des objets toggle suggèrent que les équipes marketing peuvent réorganiser, activer ou désactiver des blocs (héro, barre de confiance, sélection de produits) sans intervention technique.

Avantage : Grande flexibilité.
Inconvénient : L'existence de clés redondantes (ann et announcement) et la logique de construction en plusieurs étapes (ordre, toggles, payload) créent un risque élevé de désynchronisation.

1.5 Gestion des paramètres et sécurité

L'endpoint /api/public/settings renvoie une quantité importante de données de configuration (branding, couleurs, taxes, seuils de livraison, ID client PayPal, etc.).

Problème de sécurité majeur : Des informations potentiellement sensibles, comme l'ID fiscal (tax_id) ou des adresses emails internes, peuvent être exposées via cet endpoint public. Même le paypal_client_id est destiné à être public, mais sa présence dans une réponse JSON brute sans contexte est une pratique risquée. Tout ce qui est dans une variable window.__... est lisible par l'utilisateur final.

1.6 Paiement PayPal : Un workflow à sécuriser

Deux endpoints, /api/paypal/create-order et /api/paypal/capture, suggèrent un workflow standard :

1. Le client envoie son panier et le code promo au serveur.
2. Le serveur calcule lui-même les totaux, réductions et taxes à partir de sa base de données.
3. Il crée une commande PayPal avec le montant calculé.
4. Le client approuve le paiement dans l'interface PayPal.
5. Le serveur capture le paiement et crée la commande finale.

Règle d'or : Le serveur ne doit jamais faire confiance aux prix ou totaux envoyés par le navigateur. Le calcul doit être fait côté serveur pour éviter la fraude.

1.7 Fonctionnalités additionnelles

Les autres endpoints (review, newsletter, contact, tracking) confirment qu'il s'agit d'une application e-commerce complète. Chacun de ces points est une surface d'attaque potentielle qui nécessite des validations, des limites de taux (rate limiting) et une protection anti-spam.

2. Comparaison : Custom SPA vs. WooCommerce

2.1 Performance

• Custom SPA : Potentiel très élevé pour les navigations ultérieures (rapides comme l'éclair). Mais la première page peut être lente à cause du démarrage de l'application et de la séquence d'appels API. Le chargement de 500 produits en une seule requête est un goulot d'étranglement.
• WooCommerce traditionnel : Excellent pour la première page car l'HTML est livré avec le contenu. Cependant, il peut devenir lent si le thème est lourd, si le nombre de plugins est important ou si la base de données n'est pas optimisée.

2.2 SEO

• Custom SPA (CSR) : Risque SEO élevé. Google peut indexer le JavaScript, mais avec un délai potentiel. Le plus grand risque est la soft 404 : si une URL non valide (/product/inexistant) renvoie l'app-shell avec un code HTTP 200, Google peut la considérer comme une page valide, ce qui est préjudiciable .
• WooCommerce : Avantage SEO par défaut, car le contenu est dans l'HTML. Les balises meta et les données structurées peuvent être générées côté serveur sans effort.

2.3 Personnalisation

• Custom SPA : Liberté totale sur l'UI, les animations, les interactions. Idéal pour une marque avec des besoins de design uniques.
• WooCommerce : Limité par le thème et les plugins. Des développements sur mesure sont possibles mais peuvent être coûteux.

2.4 Maintenance

• Custom SPA : L'équipe possède et contrôle l'ensemble de la stack (frontend, backend, base de données). Cela nécessite une équipe d'ingénierie solide. Aucune dépendance à un écosystème de plugins.
• WooCommerce : La maintenance est partagée avec l'écosystème WordPress. Mettre à jour le core, le thème et les plugins peut être une source de régressions. Mais les fonctionnalités de base sont matures et testées.

2.5 Tableau de décision

3. Recommandation : une réécriture vers un rendu hybride

Le verdict est clair : l'approche SPA pure (CSR) n'est pas la meilleure solution pour un site e-commerce qui se veut visible sur les moteurs de recherche.

L'idée n'est pas de tout jeter, mais de faire évoluer l'architecture. La recommandation est de conserver la puissance de l'API REST et le constructeur de pages sur mesure, mais de réécrire le storefront en utilisant un framework de rendu hybride (SSR/ISR/SSG).

3.1 Stack technique proposée

• Storefront : Next.js (App Router) avec React 19+. Cela offre des Server Components, du SSR pour les pages critiques, du Static Site Generation (SSG) pour les pages marketing, et une hydratation sélective pour les composants interactifs (panier, menu).
• Backend : NestJS (ou Fastify) avec TypeScript pour un backend structuré et typé.
• Base de données : PostgreSQL, avec un ORM comme Prisma ou Drizzle pour les migrations et les requêtes type-safe.
• File d'attente (Queue) : BullMQ ou équivalent pour les tâches asynchrones (envoi d'emails, webhooks PayPal, génération de rapports).
• Stockage de médias : S3-compatible (et non sur le système de fichiers du serveur).

3.2 Principes clés de la réécriture

1. Normalisation du modèle de données : Le modèle produit doit être repensé autour de la variante (SKU). Chaque variante a son propre stock, son propre prix et ses propres attributs normalisés (Couleur, Taille).
2. Séparation stricte de la configuration : Les informations internes (tax_id, emails) ne doivent jamais être exposées via un endpoint public. Utiliser des variables d'environnement ou un service de configuration géré.
3. Rendre les pages indexables : Chaque page produit, catégorie et contenu important doit être disponible en HTML statique ou généré par le serveur. Les erreurs 404 doivent retourner un vrai code HTTP 404.
4. Sécuriser le tunnel de paiement : Implémenter des clés d'idempotence pour éviter les doubles paiements, des transactions pour gérer les réserves de stock, et une validation stricte des webhooks PayPal.
5. Améliorer l'observabilité : Mettre en place un logging structuré, un suivi des traces (OpenTelemetry) et un monitoring des erreurs pour chaque étape du tunnel de vente.

Conclusion

L'architecture actuelle de ce site e-commerce, avec son SPA React sur mesure, montre une intention claire de contrôle et de personnalisation. Cependant, le choix du rendu 100 % côté client est un handicap pour le SEO et la performance au premier chargement.

Pour un petit catalogue comme celui de ce site, la question de la réécriture se pose : est-ce que les bénéfices d'une architecture SSR/ISR justifient l'investissement ? Si l'ambition est de développer la marque, d'améliorer le référencement et de préparer une croissance du catalogue, la réponse est oui. La technologie (Next.js, NestJS, PostgreSQL) est mature et peut servir de base solide pour les années à venir.

En revanche, si l'objectif est de lancer rapidement avec un minimum de ressources, WooCommerce sur un hébergement géré reste une solution parfaitement valable et plus pragmatique.