Architecture multi-tenant pour SaaS avec Next.js et Supabase | Boilerplate-Stack

Le multi-tenancy, c'est quoi exactement ?

Le multi-tenancy est la capacité d'un logiciel à servir plusieurs clients (tenants) à partir d'une seule instance. Dans un SaaS, chaque tenant est généralement une organisation, une équipe ou un compte individuel. L'enjeu est d'isoler les données de chaque tenant tout en partageant l'infrastructure pour réduire les coûts.

C'est un sujet fondamental pour tout SaaS sérieux, et pourtant la plupart des boilerplates l'ignorent ou le traitent superficiellement. Boilerplate-Stack propose une implémentation complète et éprouvée du multi-tenancy.

Les trois modèles de multi-tenancy

1. Base de données séparée par tenant

Chaque client a sa propre base de données. Isolation maximale, mais complexité opérationnelle énorme : migrations, sauvegardes, connexions multiples.

Avantage : isolation totale des données
Inconvénient : coût et complexité de gestion exponentiels
Adapté pour : entreprises avec des contraintes réglementaires strictes

2. Schéma séparé par tenant

Une seule base de données mais un schéma PostgreSQL par tenant. Meilleur compromis mais les migrations deviennent complexes car il faut les appliquer à chaque schéma.

Avantage : bonne isolation, même infrastructure
Inconvénient : migrations N fois, connexions pooling complexe
Adapté pour : SaaS B2B avec des dizaines de gros clients

3. Base partagée avec Row Level Security (RLS)

Tous les tenants partagent les mêmes tables. L'isolation est assurée par des politiques RLS au niveau de PostgreSQL. C'est le modèle le plus efficace et le plus scalable.

Avantage : simplicité, performance, scalabilité
Inconvénient : nécessite une implémentation RLS rigoureuse
Adapté pour : 99% des SaaS

C'est ce troisième modèle que Boilerplate-Stack implémente, avec Supabase et PostgreSQL.

L'architecture Account-Centric

Le coeur du multi-tenancy dans Boilerplate-Stack est le modèle centré sur les comptes :

USER (auth.users)
    │
    │ peut avoir plusieurs
    ▼
MEMBERSHIPS (user_id, account_id, role_slug)
    │
    │ appartient à
    ▼
ACCOUNT (type: personal | workspace)
    ├── credits_balance
    ├── Subscriptions
    ├── Chat Sessions
    ├── AI Requests
    └── API Keys

Comptes personnels vs Workspaces

Personnel : créé automatiquement à l'inscription. 1 utilisateur = 1 compte personnel. Idéal pour le B2C.
Workspace : créé manuellement ou après checkout. N utilisateurs = 1 workspace. Invitations, rôles, gestion d'équipe.

La configuration businessModel dans config/app.ts détermine le mode :

'b2c' : comptes personnels uniquement
'b2b' : workspaces activés avec invitations et gestion d'équipe

Row Level Security en pratique

Chaque table contenant des données de tenant a une colonne account_id et une politique RLS :

CREATE POLICY "members_access" ON chat_sessions FOR SELECT
USING (EXISTS (
  SELECT 1 FROM memberships
  WHERE memberships.account_id = chat_sessions.account_id
  AND memberships.user_id = auth.uid()
));

Ce pattern garantit qu'un utilisateur ne peut accéder qu'aux données des comptes dont il est membre. La vérification se fait au niveau PostgreSQL, pas au niveau application.

Système de rôles dynamiques

Les rôles ne sont pas codés en dur. Ils sont stockés dans une table roles avec des permissions JSONB :

-- Exemple de rôle
{
  "slug": "admin",
  "permissions": {
    "manage_members": true,
    "view_billing": true,
    "manage_billing": false,
    "delete_workspace": false
  },
  "is_system": true
}

La hiérarchie est : owner > admin > member > rôles personnalisés. Les rôles système sont protégés contre la suppression. Les administrateurs peuvent créer des rôles personnalisés depuis le dashboard.

Invitations et onboarding d'équipe

Le flux d'invitation dans Boilerplate-Stack :

L'admin invite par email avec un rôle assigné
Un token d'invitation est généré (expiration 7 jours)
L'invité reçoit un email avec un lien unique
Acceptation : création du membership avec le rôle
Si l'invité n'a pas de compte, il est créé automatiquement

Account Switcher

Quand un utilisateur appartient à plusieurs comptes (personnel + workspaces), un composant Account Switcher permet de basculer entre les contextes. Toutes les données affichées (crédits, sessions, membres) changent en fonction du compte actif.

Passez au multi-tenant sans effort

Implémenter le multi-tenancy correctement est l'un des défis les plus complexes d'un SaaS. RLS, rôles, invitations, account switching — chaque pièce doit s'emboîter parfaitement.

Boilerplate-Stack fournit tout cela prêt à l'emploi, testé et documenté. Concentrez-vous sur votre produit, pas sur la plomberie multi-tenant.

Architecture multi-tenant pour SaaS : des utilisateurs solo aux équipes entreprise