veza/apps/web/AUDIT_STRATEGIQUE_FRONTEND_2025.md

# Audit stratégique frontend — Veza

**Date** : 2025-02-08  
**Équipe fictive** : Staff Frontend Engineer, Principal Product Designer, Architecte logiciel senior, Tech Lead perf/a11y/DX, Product Manager.  
**Objectif** : Diagnostic sans complaisance, écart vs Discord/Spotify, feuille de route et recommandations actionnables.

---

## A. Diagnostic brutal mais honnête

### Niveau global de l’application

**Verdict : intermédiaire à senior (6/10), avec des poches de niveau amateur et quelques bases solides.**

Justification en une phrase : *Vous avez mis en place une structure feature-based, un design system documenté, des patterns (skeletons, optimistic UI, MSW), et une batterie de tests/stories, mais l’exécution est inégale, les règles du projet sont régulièrement violées (valeurs arbitraires, double source d’auth), et le ressenti “produit fini” est entamé par des correctifs visibles (fix-*.css, patches dans main.tsx) et une cohérence a11y/UX partielle.*

- **Architecture** : Correcte en intention (features/, services/, stores/, router lazy), mais **artisanale** dans les détails (double source d’auth, callbacks no-op en route config, stores globaux vs feature stores).
- **Qualité du code** : Bonne sur les parties auditées (auth, playlists, player), **dette structurelle** (duplication auth Context vs Store, ~130 fichiers avec valeurs Tailwind arbitraires malgré une règle explicite).
- **Performance** : Bonne base (lazy routes, React Query, skeletons), mais pas de stratégie Suspense/streaming ni de priorisation explicite perçue vs mesurée. Voir *Checklist priorisation performance* ci-dessous.
- **Design system** : **Solide** sur le papier (KŌDŌ v3, tokens, layout primitives, dark mode), **fragile** en pratique (règles de layout violées massivement, pas de lint pour les primitives).
- **UX / micro-interactions** : Suffisante pour un produit interne, **insuffisante** pour un produit “premium” (feedback incohérent, états vides/erreur pas toujours traités de façon homogène).
- **Accessibilité** : Présente (aria, roles sur une partie des composants), mais **bonus** et non pilier (a11y Storybook en `todo`, pas de politique WCAG claire).
- **DX** : **Correcte** (docs internes, MSW, Storybook centralisé), mais **terrain miné** sur certains sujets (deux façons d’accéder à l’auth, nombreux fix-* à comprendre, seuils de coverage peut‑être non tenus).

---

### 5 forces réelles

1. **Design system pensé et documenté**  
   `index.css` : palette sémantique, layout primitives (`max-w-layout-content`, `min-h-layout-main`, etc.), easings, keyframes, dark mode. Les règles du projet interdisent les valeurs arbitraires et imposent ces primitives — même si non respectées partout, la cible est claire.

2. **Storybook-first et MSW bien intégrés**  
   Preview avec MSW en mode strict (`onUnhandledRequest: 'error'`), décorateur global (Theme, QueryClient, Router, Toast, Audio, Auth, i18n), pas d’import de providers dans les stories. Handlers MSW très complets (~1600 lignes). Environ 324 stories : bonne couverture de surface.

3. **Patterns de chargement et d’erreur explicites**  
   `LOADING_STATES_PATTERN.md`, composant `LoadingState` (spinner / inline / skeleton / minimal), skeletons dédiés par page (UserProfilePage, CloudFileBrowser, CourseDetailView, etc.). Données servies par React Query avec états loading/error gérés au niveau page.

4. **Optimistic UI et utilitaires métier**  
   `OPTIMISTIC_UPDATES.md` et `optimisticUpdates.ts` (createOptimisticUpdate, createArrayOptimisticUpdate, createToggleOptimisticUpdate). Utilisation dans playlists, likes, commentaires. Rollback et invalidation documentés.

5. **Surface de tests unitaires et d’intégration**  
   ~186 fichiers `*.test.tsx` et ~100 `*.test.ts`, intégration auth/playlists/player, Vitest avec coverage (seuils 80 % configurés). E2E Playwright et visuels présents. Base saine pour monter en rigueur.

---

### 5 faiblesses structurelles majeures

1. **Double source de vérité pour l’auth**  
   `AuthContext` + `useAuth()` (Storybook, ProtectedRoute, quelques pages) vs `authStore` (Zustand) + `useAuthStore()` (App, Sidebar, Login, etc.). `App.tsx` et hydratation utilisent le store ; le décorateur Storybook utilise le Context. Risque de désync, double appel à l’API, et confusion pour tout nouveau dev. Dette d’architecture prioritaire.

2. **Règles de layout systématiquement violées**  
   La règle “pas de valeurs arbitraires (w-[…], z-[…], etc.)” et “utiliser les layout primitives” est explicite dans `.cursorrules` et `index.css`, mais environ **130 fichiers** utilisent `w-[`, `h-[`, `z-[`, etc. La Sidebar elle‑même utilise `w-64`, `z-[90]`, `z-[95]`, `left-6`, `top-20`. Le design system est sous‑exploité et la cohérence visuelle fragilisée.

3. **Correctifs applicatifs visibles et fragiles**  
   `main.tsx` et `App.tsx` chargent plusieurs correctifs : `fix-input-focus.css`, `fix-login-form.css`, `fixDisplayIssues`, `fixInputFocus`. Cela indique des problèmes de conception (focus, formulaires) résolus par patch plutôt qu’à la source. Coût de maintenance et risque de régression élevé.

4. **Route config et couplage produit**  
   `routeConfig.tsx` injecte des callbacks vides dans les éléments de route : `onCreateProduct={() => {}}`, `onNavigateTrack={() => {}}`. La routing ne doit pas porter de callbacks métier ; ces props devraient remonter d’un layout ou d’un contexte. Signe que la frontière entre routing et feature n’est pas claire.

5. **Accessibilité et qualité perçue en option**  
   Storybook : `a11y: { test: 'todo' }`. Beaucoup de composants ont des `aria-*` ou `role`, mais de façon non systématique (ex. `KodoEmptyState` sans role/aria pour l’état vide, Sidebar sans `role="navigation"` ni `aria-label`). Pas de politique WCAG ni de critères de sortie a11y. L’accessibilité reste un “plus” et non un pilier, ce qui limite la maturité produit et l’inclusivité.

---

## B. Écart avec Discord & Spotify

Tableau comparatif **technique et concret** (pas d’idéalisation).

| Dimension | Discord (référence) | Spotify (référence) | Veza (état actuel) | Écart principal |
|----------|--------------------|--------------------|--------------------|------------------|
| **Architecture** | Domains clairs, state par feature, peu de global ; routing découplé du métier. | App shell léger, données par view, cache agressif. | Features + stores globaux + double auth (Context + Store). | Une seule source d’auth ; pas de callbacks dans la route config ; frontière nette layout/feature. |
| **UX** | Feedback immédiat, états loading/empty/error partout, modales et transitions prévisibles. | Transitions fluides, skeletons systématiques, pas de “trous” visuels. | Skeletons et LoadingState présents mais pas partout ; empty/error variables ; correctifs CSS. | Checklist loading/empty/error par écran ; suppression des fix-* par refonte des composants concernés. |
| **Performance** | Time to interactive court, lazy lourd, prioritisation du above-the-fold. | Streaming / progressive, cache et préchargement. | Lazy routes OK ; pas de Suspense boundary au niveau route ; pas de stratégie “perçu vs mesuré”. | Suspense + skeletons aux limites de route ; métriques perçues (LCP, INP) et objectifs chiffrés. |
| **Design** | Cohérence stricte, tokens partout, pas de valeurs en dur. | Design system unique, thème et spacing prévisibles. | Tokens et primitives définis mais ~130 fichiers en arbitraire ; primitives peu utilisées. | Lint (ou rule) qui interdit les arbitraires ; migration progressive vers primitives. |
| **Sensation de qualité** | App “qui ne bugue pas”, erreurs gracieuses, pas de demi-mesures visibles. | Polish, micro-interactions, pas de formulaires “cassés” en prod. | Correctifs visibles (fix-*), callbacks no-op, incohérences a11y. | Réduire la dette visible : un correctif = une issue de refonte ; zero no-op dans la config. |

En résumé : **Veza a les briques (design system, patterns, tests, Storybook)** mais manque de **rigueur d’exécution** (une seule auth, respect des règles de layout, accessibilité et UX traitées comme non négociables) et de **finition** (plus de polish, moins de patches) pour se rapprocher de Discord/Spotify.

---

### Checklist priorisation performance

À traiter dans cet ordre pour maximiser l’impact ressenti sans tout refactorer :

1. **First meaningful paint**  
   - Éviter tout JS bloquant avant le premier rendu (splitting par route déjà en place).  
   - S’assurer que le shell (header + sidebar ou placeholder) + un skeleton de contenu s’affichent sans attendre les données.

2. **Skeletons systématiques**  
   - Chaque page qui fetch des données doit afficher un skeleton dédié (pas un spinner générique) pendant le chargement.  
   - Déjà partiellement fait ; compléter les écrans manquants (voir Phase 2).

3. **Optimistic UI pour les actions fréquentes**  
   - Like, follow, add to playlist, etc. : mise à jour immédiate + rollback si erreur.  
   - Déjà documenté et utilisé ; étendre aux actions qui n’ont pas encore le pattern.

4. **Réduction des re-renders inutiles**  
   - Vérifier les composants lourds (listes, tableaux) : memo, sélecteurs Zustand fins, ou découpage pour limiter les sous-arbre qui se re-rendent.  
   - React Query évite déjà des refetch inutiles si `staleTime` est configuré ; auditer les queryKeys et invalidation pour éviter des cascades.

5. **Métriques et objectifs**  
   - Mesurer LCP, INP (ou FID), TTI sur les parcours critiques (login, dashboard, lecture).  
   - Fixer des objectifs (ex. LCP < 2.5 s sur 3G) et un process de revue en cas de régression.

6. **Suspense aux limites de route**  
   - Envelopper les arbres de route dans `<Suspense fallback={<PageSkeleton />}>` pour que le navigateur puisse afficher le fallback sans attendre tout le bundle enfant.  
   - Optionnel mais utile dès que le bundle par route grossit.

---

## C. Feuille de route de transformation

### Phase 1 — Fondations (ce qui doit être corrigé avant tout)

**Objectifs**  
- Une seule source de vérité pour l’auth.  
- Arrêt des correctifs “magiques” et renforcement du respect du design system.

**Actions concrètes**  
1. **Unifier l’auth**  
   - Décider : soit tout sur Zustand (authStore), soit tout sur Context (AuthProvider). Recommandation : **Zustand** (déjà utilisé par App, hydratation, Sidebar).  
   - Migrer tous les usages de `useAuth()` vers `useAuthStore()` (ou l’inverse si vous choisissez Context).  
   - Faire du AuthProvider un simple consommateur du store (s’il est gardé pour Storybook/compat).  
   - Supprimer la duplication et documenter la décision dans un ADR.

2. **Supprimer les callbacks de la route config**  
   - Retirer `onCreateProduct`, `onNavigateTrack`, etc. des éléments de route.  
   - Fournir ces comportements via layout (contexte ou props depuis un parent commun) ou navigation programmatique + state.

3. **Remplacer les fix-* par des corrections à la source**  
   - Pour chaque `fix-input-focus`, `fix-login-form`, etc. : identifier le composant (formulaire, input, focus trap) et corriger le focus, les états et le style dans le composant ou le design system.  
   - Supprimer les imports de fix-* une fois le comportement correct par défaut.

4. **Lint / règle pour les valeurs arbitraires**  
   - Règle ESLint (ou plugin Tailwind) interdisant les classes du type `w-[...]`, `h-[...]`, `z-[...]` pour layout/spacing (avec liste d’exceptions si besoin).  
   - Introduire les exceptions progressivement et traiter les ~130 fichiers par batch (par répertoire ou par feature).

**Risques**  
- Régression auth si la migration n’est pas testée (E2E login/logout, refresh, Storybook).  
- Régressions visuelles si on supprime les fix-* sans vérifier tous les écrans.

**Indicateurs de réussite**  
- Un seul mécanisme d’auth utilisé partout ; plus d’import de fix-* dans `main.tsx`/`App.tsx`.  
- Aucun callback métier dans `routeConfig.tsx`.  
- Lint en place et au moins un premier batch (ex. `components/layout`) sans violations.

---

### Phase 2 — Stabilisation et cohérence

**Objectifs**  
- Loading / empty / error systématiques.  
- Accessibilité traitée comme exigence, pas comme option.  
- Design system respecté (primitives, tokens).

**Actions concrètes**  
1. **Checklist par écran**  
   - Pour chaque page/feature : état Loading (skeleton dédié ou générique), Empty (KodoEmptyState ou équivalent), Error (ErrorDisplay + retry).  
   - Documenter la checklist et l’appliquer aux nouvelles features ; remédier les écrans existants sans état manquant.

2. **Accessibilité**  
   - Remplacer `a11y: { test: 'todo' }` par une config réelle dans Storybook (règles axe-core, seuils).  
   - Définir un niveau cible (ex. WCAG 2.1 AA) et une liste de composants critiques (formulaires, navigation, player).  
   - Corriger Sidebar (role="navigation", aria-label), KodoEmptyState (role/aria pour empty state), et autres composants identifiés par un audit axe.

3. **Migration vers layout primitives**  
   - Remplacer progressivement les valeurs arbitraires par les classes du design system (`max-w-layout-content`, `min-h-layout-main`, etc.) et l’échelle Tailwind.  
   - Prioriser : layout (Sidebar, Navbar, content), puis composants partagés (modales, cartes).

4. **Optimistic UI et erreurs**  
   - Vérifier que tous les usages d’optimistic updates ont un rollback et un feedback utilisateur en cas d’échec (toast, réversion visuelle).  
   - Centraliser la logique d’erreur (ex. `apiToastHelper`, ErrorDisplay) pour éviter des traitements ad hoc.

**Risques**  
- Scope trop large si on veut tout migrer d’un coup ; prioriser par trafic ou par criticité.

**Indicateurs de réussite**  
- Chaque écran couvert par la checklist loading/empty/error.  
- Storybook a11y activé et 0 violation sur les stories des composants critiques.  
- Réduction mesurée du nombre de violations “arbitraires” (objectif chiffré par sprint).

---

### Phase 3 — Polish et excellence perçue

**Objectifs**  
- Transitions et micro-interactions cohérentes.  
- Performance perçue (skeleton, priorisation) et mesurée (LCP, INP).  
- Réduction des “petits bugs” visuels et comportementaux.

**Actions concrètes**  
1. **Suspense et streaming**  
   - Définir des Suspense boundaries au niveau des routes (ou des sous-arbres) avec fallback skeleton.  
   - Vérifier que le premier paint utile (header + skeleton contenu) est rapide.

2. **Métriques et objectifs**  
   - Suivre LCP, INP (ou FID), TTI.  
   - Définir des objectifs (ex. LCP < 2.5 s sur 3G) et un process de revue si dégradation.

3. **Micro-interactions**  
   - Utiliser les variables déjà définies (`--duration-fast`, `--ease-out`, etc.) partout où c’est pertinent (hover, focus, modales).  
   - Passer en revue les CTA et les listes interactives pour un feedback immédiat (disabled + spinner ou état “loading” sur le bouton).

4. **Nettoyage produit**  
   - Supprimer ou documenter tout code mort et composants non utilisés.  
   - S’assurer qu’aucun no-op ou placeholder visible ne reste dans les parcours principaux.

**Risques**  
- Sur-optimisation sans mesure ; garder les métriques comme garde-fou.

**Indicateurs de réussite**  
- LCP/INP dans la cible sur les parcours critiques.  
- Pas de régression a11y ; design system respecté sur les nouvelles livraisons.

---

### Phase 4 — Scalabilité et long terme

**Objectifs**  
- Code prêt pour 10× fonctionnalités et 10× équipe.  
- Dette technique visible et pilotée.  
- Expérimentations (A/B, feature flags) sans tout casser.

**Actions concrètes**  
1. **Frontières de domaines**  
   - Clarifier ce qui vit dans `features/` vs `components/` (ex. pas de duplication forms auth dans les deux).  
   - Règle simple : composants réutilisables et design system dans `components/` ; logique métier et pages dans `features/`.

2. **State et données**  
   - Documenter quand utiliser React Query vs Zustand (server state vs client state).  
   - Éviter de dupliquer des données serveur dans des stores globaux (library, etc.) sans stratégie d’invalidation claire.

3. **Feature flags et expérimentations**  
   - Introduire un mécanisme léger de feature flags (build-time ou runtime) pour découpler déploiement et activation.  
   - Tester une feature derrière flag sans impacter les parcours principaux.

4. **Documentation et onboarding**  
   - Un README frontend à jour (structure, auth unique, design system, comment lancer Storybook et tests).  
   - Créer ou mettre à jour `docs/STORYBOOK_CONTRACT.md` (référencé dans le code) : états requis (Loading, Error, Empty), pas de providers dans les stories, MSW pour l’API.

**Risques**  
- Refactors trop larges ; privilégier des incréments et des ADR pour les décisions d’architecture.

**Indicateurs de réussite**  
- Nouveau dev opérationnel (première feature livrée) en un temps cible (ex. &lt; 2 jours).  
- Dette listée et priorisée (ex. backlog “dette” avec critères de sortie).

---

## D. Recommandations non évidentes

- **Ne pas “nettoyer” tout le code arbitraire d’un coup.**  
  Une équipe junior aurait tendance à tout remplacer en un big bang. Mieux vaut : lint qui bloque en *nouveau* code, et migration par zones (layout d’abord, puis composants partagés). Les 130 fichiers se traitent par lots avec revue visuelle et régression.

- **Traiter l’auth comme un projet de migration, pas comme une tâche.**  
  Faire un inventaire exhaustif (grep `useAuth` / `useAuthStore`), un plan de migration (ordre des fichiers), des tests E2E et Storybook qui valident login/logout/refresh, puis migrer avec une PR par zone. Un “quick fix” (tout basculer d’un coup) sans tests est risqué.

- **Ne pas activer a11y dans Storybook sans budget de correction.**  
  Activer axe avec des règles strictes du jour au lendemain va faire exploser les “failed”. Mieux : activer sur un sous-ensemble de stories (ex. composants ui/ + layout), corriger ces stories, puis élargir. a11y doit devenir un critère de merge sur les composants critiques.

- **Documenter pourquoi chaque fix-* existe.**  
  Avant de les supprimer, ajouter un commentaire ou un petit doc : “fix-login-form existe parce que …”. Cela évite de recréer le même patch plus tard et guide la refonte (quel composant doit prendre en charge le focus, etc.).

- **Mettre des indicateurs de “maturité” par feature.**  
  Une grille simple (loading / empty / error / a11y / tests / Storybook) par feature ou page. Permet de prioriser les remédiations et de ne pas prétendre que “tout est à niveau” alors que certaines zones sont encore fragiles.

- **Réserver du temps “dette” dans chaque sprint.**  
  Un projet “correct” reporte la dette ; un projet qui vise l’excellence en consacre une part fixe (ex. 20 %). Chaque sprint : X violations arbitraires en moins, Y écrans avec checklist complète, Z stories avec a11y passante.

- **Éviter d’ajouter de nouveaux stores globaux “au fil de l’eau”.**  
  Vous avez déjà auth, ui, library, cart, chat. Avant d’en ajouter un nouveau : vérifier si React Query + état local (ou store de feature) ne suffit pas. Les stores globaux multiplient les sources de vérité et compliquent le debugging et la cohérence.

---

## Synthèse

- **Niveau actuel** : Intermédiaire à senior (6/10), avec de vraies bases (design system, patterns, MSW, tests, Storybook) et des faiblesses structurelles (double auth, violations de layout, correctifs, a11y en option).
- **Écart Discord/Spotify** : Moins une question de stack que de **rigueur d’exécution** (une auth, respect des règles, a11y et UX non négociables) et de **finition** (moins de patches, plus de polish).
- **Ordre recommandé** : Fondations (auth, route config, fix-*, lint) → Stabilisation (checklist loading/empty/error, a11y, primitives) → Polish (Suspense, métriques, micro-interactions) → Scalabilité (frontières, state, flags, doc).
- **Ton** : Exigeant mais réaliste : le projet peut viser un niveau “world-class” à condition de traiter la dette identifiée comme un plan structuré et de ne pas ajouter de nouvelle dette sur l’auth et le layout.