Architecture Overview

Vue d'ensemble

Le projet suit actuellement une architecture en trois couches:

front pour l'interface et la session utilisateur
back pour l'API, la validation d'acces et les regles metier
Supabase pour l'auth, le stockage des donnees et les politiques RLS

Frontend

Le frontend Nuxt:

ouvre une session utilisateur via Supabase Auth
recupere le profil utilisateur dans profiles
conserve le contexte d'entreprise courant
appelle soit Supabase directement, soit le backend selon le niveau de migration du flux

Tests E2E frontend:

Playwright est utilise pour les parcours utilisateurs critiques
la premiere suite mocke Supabase et le backend pour stabiliser les scenarios
la CI execute cette suite mockee sur PR et sur push
une suite live dediee au staging complete la validation reelle
les rapports sont recuperes via artifacts GitHub Actions, pas via GitHub Pages par defaut

Fichiers importants:

Type de test	Outil	Emplacement	Usage
Backend unitaire/integration	Jest	`back/src/*/.spec.ts`	Logique metier et guards
Backend e2e HTTP	Jest + Supertest	`back/test`	Routes NestJS
Frontend e2e UI	Playwright	`front/e2e`	Parcours utilisateurs et permissions
Frontend e2e live	Playwright	`front/e2e-live`	Validation reelle sur staging

Suite Playwright	Cible	Mocks	Quand l'executer
`front/e2e`	Front local	Oui	PR, push, debug dev
`front/e2e-live`	Staging reel	Non	Avant release, validation staging, workflow manuel

Restitution des resultats	Emplacement	Usage
Rapport HTML local	`playwright-report` ou `playwright-report-live`	Analyse locale apres execution
Artifact GitHub Actions	Workflow run	Partage equipe et investigation CI
Videos / screenshots / traces	`test-results`	Diagnostic des echecs

Choix de publication:

les rapports ne sont pas pushes sur GitHub Pages par defaut
la raison principale est la prudence sur un projet prive avec donnees, captures et URLs de staging potentiellement sensibles

Backend

Le backend Nest:

charge back/.env via @nestjs/config
verifie le bearer token Supabase
ou verifie une API key x-api-key pour certains endpoints
charge le profile et le role de l'utilisateur
expose des routes metier protegees
utilise Supabase cote serveur avec une cle publishable ou secret

Fichiers importants:

Authentification et autorisation

Le backend distingue trois notions:

identite applicative: cle Supabase publishable ou secret
identite utilisateur: token Supabase de session
identite machine: API key geree par l'application
autorisation metier: profiles.role.slug et profiles.enterprise_id
autorisation technique: scopes portes par l'API key

Regle importante:

la cle serveur ne remplace jamais le token utilisateur
le token utilisateur ne remplace jamais la cle applicative
une API key ne remplace pas un utilisateur console
une API key ne porte jamais la cle brute en base, seulement un hash HMAC

Notion	Portee	Exemple
Identite applicative	Infrastructure	`SUPABASE_SECRET_KEY`
Identite utilisateur	Session console	Bearer Supabase
Identite machine	Integration technique	`x-api-key`
Autorisation metier	Role + entreprise	`super-admin`, `administrateur`
Autorisation technique	Scopes	`enterprises:read`

Systeme d'API keys

Architecture retenue:

CompositeAuthGuard accepte soit un bearer Supabase, soit un header x-api-key
RolesGuard continue de raisonner sur un roleSlug derive
ScopesGuard s'applique uniquement aux principals de type api_key
les utilisateurs console gardent un acces complet a leurs routes protegees par role

Stockage:

table public.api_keys
table public.api_key_usage_logs
key_hash stocke sous forme HMAC-SHA256
secret serveur dans API_KEY_SECRET
key_prefix stocke pour affichage partiel
un log detaille par appel API key avec used_at, method, path, status_code, ip

Composant	Role
`CompositeAuthGuard`	Choisit bearer Supabase ou `x-api-key`
`RolesGuard`	Applique les roles derives
`ScopesGuard`	Applique les scopes aux principals `api_key`
`ApiKeyUsageLoggingInterceptor`	Journalise les appels authentifies par cle

Consequence d'exploitation:

si API_KEY_SECRET change, toutes les API keys existantes deviennent invalides
une fuite de base seule ne suffit pas a verifier des cles candidates sans le secret applicatif

Visibilite admin:

la page super-admin des cles API affiche les metadonnees de la cle
un panneau "Voir logs" charge les 100 derniers appels pour une cle donnee
la consultation passe par GET /api-keys/:id/usage-logs

Ecran super-admin	Donnees visibles
Liste des cles	libelle, prefixe, portee, scopes, expiration, dernier usage, statut
Detail des logs	date, methode, route, code HTTP, IP

Flux technique:

text

Requete entrante
  -> CompositeAuthGuard
    -> bearer Supabase ? SupabaseAuthGuard
    -> sinon x-api-key ? ApiKeyAuthGuard
  -> RolesGuard
  -> ScopesGuard
  -> Controller/Service
  -> ApiKeyUsageLoggingInterceptor
  -> insertion dans api_key_usage_logs

Strategie de migration

Strategie actuelle:

migrer d'abord les lectures metier a fort impact
conserver le frontend fonctionnel pendant la transition
centraliser progressivement les acces sensibles dans back

Etat du domaine enterprises:

fetchAll() passe par GET /enterprises sur back
GET /enterprises exclut explicitement les entreprises de type personal
fetchById() et les mutations restent cote front vers Supabase

Tests

Deux niveaux de tests existent sur le backend pour enterprises:

tests unitaires sur la logique metier du service
tests d'integration backend avec guards reels et SupabaseService mocke

Fichiers:

Architecture Overview ​

Vue d'ensemble ​

Frontend ​

Backend ​

Authentification et autorisation ​

Systeme d'API keys ​

Strategie de migration ​

Tests ​