ansiblenginx/app/bricolociaac/docs/architecture/ADR/003-backend-supabase.md

ADR-003 : Supabase comme Backend et Base de Données

Statut : ✅ Accepté
Date : Octobre 2025
Décideurs : Équipe Architecture
Tags : backend, database, baas

---

Contexte

L'application moderne nécessite :

• Base de données PostgreSQL
• Authentification sécurisée
• API pour accès aux données
• Temps réel (stocks, notifications)
• Storage (images d'outils)

Contrainte : MCP Supabase disponible (accès privilégié)

Options considérées

1. Supabase (BaaS - Backend as a Service)
2. Firebase (Google)
3. PocketBase (self-hosted)
4. PostgreSQL + Backend custom (Node.js/Express)

---

Décision

✅ Nous adoptons Supabase comme backend et base de données

---

Justification

Pourquoi Supabase ?

1. PostgreSQL Véritable 🐘

• Base de données relationnelle complète
• SQL standard (pas de limitations Firebase)
• Triggers, fonctions, vues, index
• Relations complexes possibles
• Migration facilitée (si besoin)

2. Authentification Intégrée 🔐

• Supabase Auth : JWT, session management
• Providers OAuth (Google, GitHub, etc.)
• Row Level Security (RLS) : sécurité au niveau BDD
• Magic links, OTP
• Gestion des rôles

3. Realtime Built-in ⚡

• Supabase Realtime : WebSocket automatique
• Écoute des changements BDD (INSERT, UPDATE, DELETE)
• Broadcast : Pub/Sub pour events
• Presence : utilisateurs connectés
• Parfait pour stocks temps réel ✅

4. API Auto-générée 🚀

• PostgREST : API REST générée depuis schéma
• GraphQL (expérimental)
• SDK JavaScript/TypeScript officiel
• Queries filtrables, triables, paginables

5. Storage Intégré 📦

• Supabase Storage : stockage de fichiers
• Images d'outils (avec CDN)
• Buckets publics/privés
• Intégration RLS

6. Developer Experience 💻

• Dashboard web complet
• Migrations SQL versionnées
• Logs en temps réel
• MCP Supabase : accès privilégié ✅

7. Gratuit pour Démarrer 💰

• Tier gratuit généreux
• 500 MB database
• 1 GB storage
• 2 GB bandwidth
• Suffisant pour projet académique

8. Écosystème Next.js 🔗

• Intégration Next.js excellente
• SSR support (@supabase/ssr)
• Middleware auth Next.js
• Exemples officiels

---

Comparaison des Alternatives

Critère	Supabase	Firebase	PocketBase	Postgres Custom
Type BDD	PostgreSQL	NoSQL	SQLite	PostgreSQL
SQL	✅ Complet	❌ Non	✅ Oui	✅ Complet
Realtime	✅✅✅ Natif	✅ Natif	⚠️ Manuel	❌ À développer
Auth	✅ Intégré	✅ Intégré	✅ Intégré	❌ À développer
API	✅ Auto-généré	✅ SDK	✅ Auto	❌ À développer
Storage	✅ Intégré	✅ Intégré	✅ Intégré	❌ AWS S3 séparé
Open Source	✅ Oui	❌ Non	✅ Oui	✅ Oui
Self-hosted	⚠️ Docker	❌ Non	✅ Facile	✅ Oui
Prix	✅ Gratuit start	⚠️ Pay-as-go	✅ Gratuit	⚠️ Hébergement
Communauté	✅✅	✅✅✅	✅	✅✅
MCP	✅ Disponible	❌ Non	❌ Non	❌ Non

---

Architecture avec Supabase

Vue d'Ensemble

┌─────────────────────────────────────────┐
│      Next.js App (Frontend + BFF)       │
└────────┬───────────────────────┬────────┘
         │                       │
         │ Supabase Client       │ Server API
         │                       │
┌────────▼───────────────────────▼────────┐
│           Supabase Platform             │
│  ┌─────────────────────────────────┐   │
│  │  PostgreSQL + PostgREST (API)   │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │  Supabase Auth (JWT + OAuth)    │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │  Supabase Realtime (WebSocket)  │   │
│  └─────────────────────────────────┘   │
│  ┌─────────────────────────────────┐   │
│  │  Supabase Storage (CDN)         │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘

Utilisation par Microservice

Microservice	Usage Supabase
Auth Service	Supabase Auth (géré)
Catalogue Service	Tables outils, categories
Reservation Service	Table reservations
Inventory Service	Table stocks + Realtime
Payment Service	Table transactions (logs)
Notification Service	Realtime Channels (events)

Row Level Security (RLS)

-- Exemple : Les utilisateurs ne voient que leurs réservations
CREATE POLICY "Users can view own reservations"
ON reservations FOR SELECT
USING (auth.uid() = utilisateur_id);

-- Exemple : Les utilisateurs peuvent créer leurs propres réservations
CREATE POLICY "Users can create reservations"
ON reservations FOR INSERT
WITH CHECK (auth.uid() = utilisateur_id);

Avantage : Sécurité au niveau BDD (pas de bypass possible)

---

Realtime pour Stocks

Problème Legacy

• Synchronisation quotidienne (batch CSV)
• Décalage 24h ❌
• Incohérences fréquentes

Solution Supabase Realtime

// Écoute des changements stocks en temps réel
const channel = supabase
  .channel('stocks-changes')
  .on(
    'postgres_changes',
    {
      event: 'UPDATE',
      schema: 'public',
      table: 'stocks'
    },
    (payload) => {
      console.log('Stock updated:', payload.new)
      // Mise à jour UI automatique
      updateStockCache(payload.new)
    }
  )
  .subscribe()

Résultat : Stocks temps réel ⚡ (0 décalage)

---

Event Bus avec Realtime Channels

// Service A émet un event
await supabase.channel('events')
  .send({
    type: 'broadcast',
    event: 'reservation.created',
    payload: { reservationId, outilId }
  })

// Service B écoute l'event
supabase.channel('events')
  .on('broadcast', { event: 'reservation.created' }, (payload) => {
    console.log('Reservation created:', payload)
    // Déclencher logique métier
  })
  .subscribe()

Utilisation : Communication asynchrone entre microservices

---

Conséquences

✅ Avantages

1. Productivité : Backend prêt à l'emploi (gain de temps)
2. Realtime natif : Problème stocks résolu ✅
3. Sécurité : RLS + JWT built-in
4. Scalabilité : Infrastructure gérée (pas d'ops)
5. MCP : Accès privilégié via Copilot ✅
6. Open Source : Pas de vendor lock-in (self-host possible)
7. Migrations : Versionnées et traçables
8. Dashboard : Monitoring et logs

⚠️ Inconvénients

1. Abstraction : Moins de contrôle qu'un backend custom
2. Limites tier gratuit : 500 MB database (suffisant pour démo)
3. Courbe apprentissage : Concepts spécifiques (RLS, Realtime)
4. Vendor : Dépendance à Supabase (mais mitigée par open source)

🛠️ Mitigations

• Abstraction : Repository Pattern isole Supabase
• Limites : Projet académique = tier gratuit OK
• Apprentissage : Documentation excellente
• Vendor lock-in : PostgreSQL standard = migration possible

---

Alternatives Rejetées

❌ Firebase

Avantages :

• Écosystème Google mature
• Très populaire

Raisons du rejet :

• NoSQL (Firestore) : moins adapté que SQL
• Queries limitées (pas de JOIN)
• Pas de MCP disponible
• Moins "impressionnant" techniquement (trop simple)

❌ PocketBase

Avantages :

• Ultra simple (1 fichier Go)
• SQLite (léger)
• Self-hosted facile

Raisons du rejet :

• SQLite : moins robuste que PostgreSQL
• Moins adapté pour microservices
• Communauté plus petite
• Pas de MCP

❌ PostgreSQL + Backend Custom

Avantages :

• Contrôle total
• Flexibilité maximale

Raisons du rejet :

• Trop de temps de développement (auth, API, realtime)
• Focus projet = architecture, pas infra
• Realtime difficile à implémenter
• Pas de valeur ajoutée pour démonstration

---

Références

• Supabase Documentation
• Supabase Realtime
• Row Level Security
• Supabase + Next.js
• MCP Supabase

---

Validations

• Compte Supabase créé
• MCP Supabase configuré ✅
• POC Realtime testé
• RLS policies validées
• Intégration Next.js OK

---

Prochaine révision : Si limitations découvertes lors du développement