DOC
Accueil/ Projets/ KOBIKE Tracking Notifier/ ADR 0003 : Stack technologique pour l'application de gestion client

ADR 0003 : Stack technologique pour l'application de gestion client

  • Statut : Proposé
  • Date : 2026-07-13
  • Auteur : Antigravity

Contexte

Afin de gérer les informations des clients (notamment pour associer ou modifier manuellement leurs adresses email), nous devons créer une application web simple, robuste et légère. L'application doit pouvoir s'interfacer avec la base de données PostgreSQL déjà déployée sur notre VPS via Coolify, et permettre aux équipes en magasin de renseigner rapidement les informations manquantes ou erronées.

Options étudiées

Option 1 : Stack Python (FastAPI) & React (Vite)

  • Frontend : Application monopage (SPA) construite en React avec l'outil de build Vite. Utilisation de Vanilla CSS pour un rendu épuré et performant sans surcouche complexe.
  • Backend : API REST construite avec Python (FastAPI) communiquant avec PostgreSQL via SQLModel ou SQLAlchemy.
  • Avantages :
    • Séparation claire des responsabilités (découplage Frontend/Backend).
    • FastAPI est extrêmement performant, léger et auto-documenté (Swagger UI généré automatiquement).
    • React + Vite offre une expérience utilisateur fluide et interactive (idéal pour la recherche et l'édition dynamique).
    • Validation stricte des données (Pydantic pour les emails et téléphones).
  • Inconvénients :
    • Nécessite le déploiement et la maintenance de deux environnements distincts (le serveur FastAPI et le build statique React).

Option 2 : Stack Full Python (Streamlit / NiceGUI / Reflex)

Utilisation d'un framework Python unifié qui gère à la fois l'interface utilisateur et la logique backend (sans écrire de Javascript).

  • Avantages :
    • Codebase unique en Python.
    • Développement ultra-rapide pour des prototypes internes.
  • Inconvénients :
    • Streamlit est peu adapté pour des interfaces de gestion complexes à forte interactivité ou multi-utilisateurs.
    • NiceGUI et Reflex ont des communautés plus restreintes et offrent moins de flexibilité de design que React pour une application de production à long terme.

Option 3 : Utilisation directe de NocoDB (No-code)

NocoDB est déjà installé sur le VPS et connecté à PostgreSQL. Il offre une interface similaire à Airtable.

  • Avantages :
    • Déjà disponible et configuré.
    • Aucune ligne de code à écrire pour les vues de base.
  • Inconvénients :
    • Interface générique peu adaptée à un flux métier spécifique (ex: recherche par code-barres, validation métier, alertes d'emails manquants).
    • Difficile d'intégrer des fonctionnalités sur mesure comme un portail client public ou des boutons d'actions personnalisés (ex: "Renvoyer l'email de suivi").

Décision

L'Option 1 (FastAPI + React/Vite) est retenue pour sa robustesse, sa maintenabilité à long terme et sa capacité à s'adapter précisément aux besoins métiers. L'accès direct à NocoDB (Option 3) sera conservé en parallèle pour les administrateurs afin d'effectuer des modifications de données en masse ou des exports rapides.

Hébergement (VPS Coolify et/ou Netlify)

Le découplage front/back rend l'hébergement souple et simple :

  • Backend FastAPI : conteneur Docker sur le VPS via Coolify, sur le même réseau interne que PostgreSQL/NocoDB/n8n (pas d'exposition publique de la base). Exposé en HTTPS derrière le reverse-proxy de Coolify.
  • Frontend React/Vite : c'est un build statique (npm run build → dossier dist/). Deux options équivalentes, au choix :
    • Netlify (le plus simple) : build automatique depuis le repo Git, CDN, HTTPS gratuit. Configurer la variable d'environnement VITE_API_URL pointant vers l'URL publique du backend Coolify, et gérer le CORS côté FastAPI pour autoriser le domaine Netlify.
    • VPS/Coolify : servir dist/ via un conteneur statique (Nginx/Caddy) - tout reste sur la même machine, pas de CORS cross-domaine.
  • Recommandation : commencer tout sur le VPS Coolify (front + back + base), plus simple à sécuriser et sans CORS ; basculer le front sur Netlify seulement si l'on veut un CDN/déploiements front indépendants. Garder le frontend sans dépendance à un backend co-localisé (appels via VITE_API_URL) pour pouvoir déplacer l'un ou l'autre sans réécriture.

Conséquences

  • Positives :
    • API REST FastAPI réutilisable pour d'autres intégrations futures.
    • Interface utilisateur React réactive, fluide et adaptée au personnel en magasin.
    • Typage fort et validation automatique des données en entrée (sécurité accrue).
    • Hébergement flexible : 100 % VPS, ou front Netlify + back VPS, sans changer le code.
  • Négatives :
    • Nécessite d'initialiser deux répertoires de code (un dossier backend Python et un dossier frontend React).
    • Si le front est sur Netlify et le back sur le VPS, il faut gérer le CORS et une variable d'URL d'API.
    • Temps de développement initial légèrement supérieur à celui d'une solution 100% no-code.