Outil BDD

Appearance

🧱 Decisions d'architecture (ADR) ​

📐Pourquoi cette page existe

Les ADR tracent les choix structurants du projet. Elles evitent de rediscuter les memes arbitrages a chaque ticket et rendent les compromis explicites.

mermaid
timeline
    title Principaux arbitrages structurants
    MVP 0 : PostgreSQL metier separe
          : Scaleway Object Storage
          : AUTH centralise partage
    MVP 0+ : Upload via NestJS
           : Soft delete
           : Synchronisation via cron

ADR-01 — PostgreSQL independant plutot que Supabase DB ​

Statut : Accepte

Contexte : Supabase fournit une base PostgreSQL integree. Il aurait ete possible d'y stocker les donnees metier de l'Outil BDD.

Decision : Les donnees metier de l'Outil BDD sont stockees dans une instance PostgreSQL independante, distincte de Supabase.

Raisons :

  • Decouplage fort entre l'authentification (Supabase) et les donnees applicatives
  • Evite la dependance a un fournisseur unique pour les donnees critiques
  • Permet de faire evoluer ou migrer la BDD metier sans impacter l'auth
  • Coherence avec le reste de l'infrastructure (Scaleway, AWS) qui privilegie des services independants

Consequences :

  • La table users en BDD metier reference le supabase_uid comme cle etrangere logique
  • Le backend NestJS gere deux connexions distinctes : Supabase Auth (SDK) et PostgreSQL (ORM)

ADR-02 — Scaleway Object Storage plutot que Supabase Storage ​

Statut : Accepte

Contexte : Supabase propose un service de stockage de fichiers (Supabase Storage) compatible S3. Il aurait ete naturel de l'utiliser puisque Supabase est deja dans le stack.

Decision : Le stockage des fichiers clients est assure par Scaleway Object Storage (compatible S3).

Raisons :

  • Coherence avec l'infrastructure existante (Scaleway deja utilise dans d'autres projets)
  • Souverainete des donnees : hebergement en Europe (Paris)
  • Tarification previsible et independante du quota Supabase
  • Compatibilite S3 native : le client AWS SDK fonctionne sans modification

Consequences :

  • Le backend NestJS integre le SDK AWS S3 configure sur l'endpoint Scaleway
  • Les URLs pre-signees sont generees par NestJS, pas par Supabase

ADR-03 — Upload de fichiers via NestJS ​

Statut : Accepte

Contexte : Deux approches possibles pour l'upload de fichiers : transit par le backend NestJS, ou upload direct vers S3 via URL pre-signee.

Decision : L'upload se fait via le backend NestJS, qui recoit le fichier, le valide, puis le transfere vers Scaleway S3.

Raisons :

  • Controle d'acces : le jeton applicatif emis par AUTH est verifie par NestJS avant tout upload
  • Controle du contenu : validation de la presence du fichier, de la taille et des droits avant stockage
  • Tracabilite complete : NestJS enregistre qui a uploade quoi, quand et dans quel dossier
  • Implementation plus simple et plus facile a deboguer
  • Les fichiers traites (tout type, max 50 Mo par defaut) ne generent pas de surcharge significative

Consequences :

  • Le flux est en deux temps : (1) frontend envoie le fichier a NestJS (multipart/form-data), (2) NestJS valide et transfere vers S3
  • NestJS est le seul point d'entree pour les fichiers
  • Si les volumes augmentent significativement, une migration vers l'upload direct S3 pourra etre envisagee

ADR-04 — AUTH partage avec la console d'administration ​

Statut : Accepte

Contexte : L'Outil BDD est distinct de la console d'administration existante. Il aurait ete possible de creer un projet Supabase dedie.

Decision : L'Outil BDD s'appuie sur le portail AUTH et l'authentification partagee de la console d'administration existante.

Raisons :

  • Les utilisateurs sont deja provisionnes dans le systeme d'authentification existant
  • Evite la duplication de la gestion des comptes et des entreprises
  • Single Sign-On implicite : un utilisateur deja connu de la console admin peut acceder a l'Outil BDD sans creer un nouveau compte
  • Reduction du nombre de systemes d'authentification a maintenir

Consequences :

  • L'Outil BDD depend du portail AUTH de la console admin
  • La gestion des comptes reste dans la console admin — l'Outil BDD ne propose pas d'ecran de gestion des utilisateurs
  • Le backend NestJS valide exclusivement app_access_token, emis par AUTH

ADR-05 — Soft delete pour les utilisateurs et les entreprises ​

Statut : Accepte

Contexte : Lorsqu'un utilisateur ou une entreprise est supprime dans la console d'administration, il faut decider de l'impact sur les donnees de l'Outil BDD.

Decision : La suppression est un soft delete : l'entite est marquee comme supprimee (deleted_at) mais les donnees sont conservees. Un super admin peut effectuer un hard delete pour supprimer definitivement.

Raisons :

  • Evite la perte accidentelle de donnees (fichiers deposes, dossiers)
  • Permet de conserver une tracabilite meme apres depart d'un utilisateur
  • Le hard delete reste possible pour repondre aux demandes RGPD
  • La revocation d'acces est immediate via AUTH (jeton applicatif refuse ou non emis)

Consequences :

  • Les tables users et entreprises ont un champ deleted_at (nullable — null = actif)
  • Un utilisateur soft-delete ne peut plus se connecter mais ses fichiers sont conserves
  • La suppression d'une entreprise entraine le soft delete de tous ses utilisateurs et dossiers en cascade
  • Seul un super admin peut declencher un hard delete
  • Les requetes API filtrent systematiquement WHERE deleted_at IS NULL

ADR-06 — Synchronisation console admin via job cron ​

Statut : Depasse

Contexte : L'Outil BDD doit maintenir ses tables synchronisees avec la console d'administration. Deux approches evaluees : webhooks (temps reel) ou job cron (periodique).

Decision initiale : la synchronisation etait assuree par un job cron NestJS qui s'executait toutes les minutes. Il appelait l'API de la console admin, comparait les donnees avec la BDD metier et appliquait les creations, modifications et soft deletes necessaires.

L'environnement est defini par les variables ENVIRONMENT et APPLICATION. Seules les entreprises associees a cet environnement sont synchronisees.

Raisons :

  • Simplicite d'implementation — pas de gestion de signatures HMAC, d'endpoints dedies ni de logique de retry
  • Toujours operationnel — fonctionne meme si des evenements ont ete manques
  • L'API de la console admin est le seul point de verite — pas d'acces direct a sa BDD
  • Desynchronisation maximale acceptable pour le MVP 0
  • Decouplage fort : l'Outil BDD ne connait pas la structure interne de la BDD de la console admin

Etat actuel :

  • la synchronisation d'identite a ete retiree
  • l'acces a BDD repose sur AUTH -> app_access_token
  • l'utilisateur local est provisionne a la connexion
  • les lectures externes restantes passent par l'API console-admin