veza/sub_task_agents/frontend_only/FULL_FRONTEND_AUDIT.md

I'll conduct this audit systematically by exploring the entire frontend codebase. Let me start by gathering information across multiple dimensions in parallel.

[4 tools called]

Now let me dig deeper into specific critical areas I need to validate.

[1 tool called]

Let me now gather a few more specific data points needed for the final audit.

[6 tools called]

Good - no cross-feature imports. Let me check a few more things.

[5 tools called]

Now I have all the data I need for a comprehensive audit. Let me compile the final report.

---

AUDIT TECHNIQUE INTÉGRAL — FRONTEND & DESIGN SYSTEM

Projet : Veza — Plateforme Audio Collaborative
Date : 13 février 2026
Auditeur : Architecte frontend indépendant
Branche : main
Dernière mise à jour du document : 13 février 2026

---

1. EXECUTIVE SUMMARY

Ce frontend est techniquement ambitieux et structurellement solide, mais souffre d'un décalage significatif entre l'ampleur du code produit et la maturité réelle du produit. L'architecture est bien pensée (feature-based, lazy loading, stores Zustand, React Query, i18n), le design system SUMI v2.0 est remarquablement complet dans sa couche tokens/CSS, et la couverture de tests (~287 fichiers) et stories (~323 fichiers) est substantielle.

Cependant : au moins 5 routes majeures pointent vers des placeholders "Coming Soon" (Gear, Live, Education, Queue, Developer), 3 feature flags restent désactivées par défaut (PLAYLIST_RECOMMENDATIONS, HLS_STREAMING, ROLE_MANAGEMENT) ; NOTIFICATIONS et PLAYLIST_SHARE sont à true, le code contient des any dans des services critiques (auth), des setTimeout sans cleanup, et la base de code frôle le surdimensionnement pour un produit en phase MVP. Le risque principal n'est pas la qualité du code mais la dispersion : trop de surface frontale pour un backend partiellement implémenté. Un investisseur verrait un produit impressionnant en démo superficielle, mais fragile dès qu'on sort du chemin heureux.

Verdict : Refactoring ciblé, pas de réécriture. Score global : 6.8/10.

---

2. CARTOGRAPHIE FRONTEND

Stack & Tooling

Composant	Technologie	Version
Framework	React	^18.2.0
Language	TypeScript	^5.3.3
Build tool	Vite	^7.1.5
State management	Zustand + Immer	^4.5.0 / ^10.0.3
Routing	React Router DOM	^6.22.0
Data fetching	TanStack React Query + Axios	^5.17.0 / ^1.13.5
CSS	Tailwind CSS v4 (CSS-first)	^4.0.0
Forms	React Hook Form + Zod	^7.49.3 / ^3.25.76
i18n	i18next + react-i18next	^25.5.2 / ^15.7.3
Animation	Framer Motion	^12.29.2
Icons	Lucide React	^0.321.0
Monitoring	Sentry	^10.32.1
Linting	ESLint 9 (flat config)	^9.0.0
Formatting	Prettier	^3.2.5
Testing	Vitest + Testing Library + Playwright	^3.2.4 / ^14.2.1 / ^1.58.2
Storybook	Storybook	^8.6.15
Mocking	MSW	^2.11.2

Organisation du code

src/
├── app/               # Root component
├── components/        # Composants partagés (~248 UI + ~545 feature-specific)
│   ├── ui/            # Primitives design system (248 fichiers)
│   ├── layout/        # Header, Sidebar, DashboardLayout
│   ├── admin/         # Admin components
│   ├── auth/          # Auth components
│   ├── settings/      # Settings (57 fichiers)
│   ├── social/        # Social features
│   ├── studio/        # Studio/editing (76 fichiers)
│   └── views/         # View components (211 fichiers)
├── config/            # Feature flags, env, constants
├── context/           # AudioContext, AuthContext
├── features/          # Feature modules (878 fichiers)
│   ├── tracks/        # 189 fichiers — plus gros module
│   ├── playlists/     # 148 fichiers
│   ├── player/        # 77 fichiers
│   ├── chat/          # 56 fichiers
│   ├── auth/          # Complet
│   ├── search/        # 23 fichiers
│   └── ... (14 autres features)
├── hooks/             # 41 custom hooks
├── services/          # 28 fichiers API/domain services
├── stores/            # 11 Zustand stores
├── types/             # 144 fichiers de types
├── locales/           # en.json, fr.json (~528 lignes chaque)
├── mocks/             # MSW handlers (1717 lignes)
└── utils/             # 50+ utilitaires

Mise à jour 13/02/2026 : mocks/handlers.ts ~1606 lignes ; services/api/interceptors.ts ~1203 lignes.

Convention de nommage : PascalCase pour composants, camelCase pour hooks/utils/services. Cohérent.

Découpage : Hybride feature-based + type-based. Le dossier components/ contient à la fois des UI primitives (ui/) et des composants feature-specific (admin/, social/, studio/, views/) qui devraient logiquement vivre dans features/. Cette duplication structurelle crée une ambiguité : un développeur cherchant les composants social ne sait pas s'il doit regarder components/social/ ou features/social/.

Co-location : Partielle. Les features co-localisent composants + hooks + services + types. Mais les tests sont co-localisés avec les composants (bon), tandis que les stories sont parfois dans le même dossier, parfois dans stories/ (incohérent).

Barrel exports : Présents dans les modules UI (LazyComponent.ts, lazyExports.ts). Pas de barrel systématique par feature.

Dépendances — Analyse critique

Redondances identifiées :

• Spinner.tsx + LoadingSpinner.tsx + LoadingState.tsx : trois composants de loading différents
• Modal.tsx (marqué deprecated) + Dialog.tsx : coexistence avec note de migration inachevée
• components/feedback/Alert.tsx potentiellement dupliqué avec components/ui/alert.tsx

Dépendances lourdes :

• swagger-ui-react + swagger-ui-dist (^5.31.0) : en devDependencies (corrigé).
• framer-motion (^12.29.2) : justifié pour les animations, mais certaines animations CSS pures suffiraient
• emoji-picker-react (^4.16.1) : lazy-loaded (correct)

Dépendances en production qui devraient être en dev :

• rollup-plugin-visualizer (^6.0.5) : dans dependencies au lieu de devDependencies

Tree-shaking : Lucide React est correctement importé par icône individuelle. TanStack et date-fns sont tree-shakeable. Le chunk splitting manuel dans vite.config.ts est fonctionnel mais basique (tout node_modules non catégorisé va dans un seul chunk vendor).

---

3. INVENTAIRE DESIGN SYSTEM

Maturité : Niveau 3.5 / 4

Le design system SUMI v2.0 ("L'encre et la lumière") est remarquablement complet en tokens mais incomplètement consommé par les composants.

Tokens & Variables

Forces :

Catégorie	État	Détail
Couleurs	Sémantique	--sumi-bg-void à --sumi-bg-wash, accents (vermillion, sage, gold), états sémantiques (success, warning, error, info)
Typographie	Complet	4 familles (Inter, Space Grotesk, JetBrains Mono, Noto Serif JP), échelle xs à 4xl, weights, tracking, leading
Espacement	Complet	Échelle 0.5 (2px) à 20 (80px) sur base 4px
Radius	Complet	xs (2px) à full (9999px)
Shadows	Complet	xs à 2xl + glow effects
Motion	Complet	Durées (75ms à 500ms), easings (6 courbes), transitions prédéfinies
Z-index	Complet	Échelle base (0) à max (999)
Layout	Complet	Max-widths, sidebar, header, player dimensions
Dark/Light	Fonctionnel	Dark par défaut, light mode avec overrides complets
Glass effects	Défini	--sumi-glass-bg, --sumi-glass-border, --sumi-glass-blur

Localisation : Tous les tokens vivent dans src/index.css via @theme inline de Tailwind v4. C'est un fichier unique, bien organisé par sections. Les tokens sont mappés vers les utilities Tailwind correctement.

Faiblesses :

• Les tokens sont définis dans CSS mais certains composants utilisent des valeurs Tailwind directes (rounded-xl) au lieu de rounded-[var(--sumi-radius-xl)] — incohérence entre ce qui est déclaré et ce qui est consommé.
• ~100+ valeurs arbitraires Tailwind trouvées dans le code source (bien que beaucoup soient dans les stories ou des cas justifiés comme les SVG).

Composants UI — Inventaire classé

Composants solides (reusables, testés, accessibles) :

Composant	Imports	Tests	A11y	Notes
Button	~150+	button.test.tsx	Focus ring, ARIA	8 variants, 4 sizes, loading state
Card	~150+	card.test.tsx	Standard	9 variants, 4 paddings, spotlight effect
Input	~70+	input.test.tsx	aria-invalid, describedby	Icon, label, error props
Skeleton	~100+	skeleton.test.tsx	aria-hidden	3 variants
Checkbox	~15+	checkbox.test.tsx	useId, aria-label	Proper labeling
Switch	Low	switch.test.tsx	role="switch", aria-checked	Complete
RadioGroup	Low	radio-group.test.tsx	Arrow key nav, tabIndex	Full keyboard support
Slider	Low	slider.test.tsx	aria-valuenow/min/max	Complete ARIA
Badge	~20+	badge.test.tsx	Standard	Multiple variants, pulse
Alert	~10+	alert.test.tsx	role="alert"	6 variants, dismissible
Progress	~5+	progress.test.tsx	role="progressbar", ARIA	Gaming variant
Dialog	~30+	dialog.test.tsx	role="dialog", aria-modal	Focus trap
Tabs	~10+	tabs.test.tsx	Tab pattern	Sub-components
Table	None found	table.test.tsx	aria-label, sortable	Complete sub-components
Avatar	~15+	avatar.test.tsx	Standard	7 sizes, 6 status
Tooltip	Low	tooltip.test.tsx	Standard	Multiple positions
FocusTrap	Internal	focus-trap.test.tsx	Tab trapping, Escape	Used by Dialog/Modal
Select	~20+	select.test.tsx	aria-label	Searchable, multi
ScrollArea	Low	scroll-area.test.tsx	Standard	Custom scrollbar

Composants fragiles (fonctionnels mais problématiques) :

Composant	Problème	Impact
ErrorDisplay	Testé (ErrorDisplay.test.tsx)	—
LoadingState	Testé (LoadingState.test.tsx)	—
Accordion	Testé (Accordion.test.tsx)	—
Collapsible	Testé (collapsible.test.tsx)	—
FAB	Testé (FAB.test.tsx)	—
FloatingInput	Testé (floating-input.test.tsx), utilise oklch() hardcodé	Hors design system (mineur)
TrackCard	Utilise (track as any).like_count (l.43)	Contournement TypeScript
Modal	Marqué deprecated mais encore 6+ imports	Migration inachevée

Composants morts ou en doublon :

Composant	Statut
Spinner.tsx + LoadingSpinner.tsx + LoadingState.tsx	3 implémentations du même concept
Modal.tsx (deprecated)	Coexiste avec Dialog.tsx — 6 fichiers l'importent encore
components/feedback/Alert.tsx	Potentiel doublon de components/ui/alert.tsx
ComingSoon.tsx	Testé (ComingSoon.test.tsx)
AnimatedNumber.tsx	Testé (AnimatedNumber.test.tsx)

Cohérence visuelle

!important : 4 occurrences dans index.css, toutes justifiées (réduction de mouvement prefers-reduced-motion et animation d'entrée player). Aucun !important abusif.

Styles inline contredisant le système : Non identifiés (les composants utilisent cn() de clsx/tailwind-merge systématiquement).

Espacements : Cohérents — la majorité utilise l'échelle Tailwind native (gap-2, p-4, space-y-1). Les valeurs arbitraires sont concentrées dans les stories et les cas justifiés (SVG charts).

Typographie : L'échelle est définie mais les classes utilitaires SUMI (sumi-h1, sumi-body, etc.) coexistent avec les classes Tailwind standard (text-xs, font-medium). Double système typographique non unifié.

---

4. DIAGNOSTIC FONCTIONNEL — CE QUE LE FRONTEND PERMET RÉELLEMENT

Pages/Views fonctionnelles

Route	Composant	État
/login	LoginPage	Fonctionnel (MSW)
/register	RegisterPage	Fonctionnel (MSW)
/forgot-password	ForgotPasswordPage	Fonctionnel (MSW)
/verify-email	VerifyEmailPage	Fonctionnel (MSW)
/reset-password	ResetPasswordPage	Fonctionnel (MSW)
/dashboard	DashboardPage	Fonctionnel (MSW, données statiques)
/library	LibraryPage	Fonctionnel (MSW)
/tracks/:id	TrackDetailPage	Fonctionnel (MSW)
/playlists/*	PlaylistRoutes	Fonctionnel (MSW, collaboration)
/chat	ChatPage	Fonctionnel (MSW)
/search	SearchPage	Fonctionnel (MSW)
/settings	SettingsPage	Fonctionnel (MSW)
/settings/sessions	SessionsPage	Fonctionnel (MSW)
/profile	UserProfilePage	Fonctionnel (MSW)
/u/:username	UserProfilePage (public)	Fonctionnel
/social	SocialView	Fonctionnel (MSW)
/notifications	NotificationsPage	Fonctionnel (MSW)
/marketplace	MarketplaceHome	Fonctionnel (MSW)
/design-system	DesignSystemDemo	Fonctionnel (statique)

Pages partiellement implémentées

Route	État	Détail
/analytics	MSW-only	Backend NOT IMPLEMENTED (config/features.ts)
/webhooks	MSW-only	Backend MSW-only
/admin	MSW-only	Backend partiellement implémenté
/admin/roles	MSW-only, flag ROLE_MANAGEMENT: false	Backend NOT IMPLEMENTED
/sell	MSW-only	Commerce backend non confirmé
/wishlist	MSW-only	Commerce backend non confirmé
/purchases	MSW-only	Commerce backend non confirmé

Pages mortes (Coming Soon)

Route	Statut
/gear	ComingSoon placeholder
/live	ComingSoon placeholder
/education	ComingSoon placeholder
/queue	ComingSoon placeholder
/developer	ComingSoon placeholder

Feature flags désactivés par défaut

Flag	Default	Raison documentée
PLAYLIST_SEARCH	false	Backend pas implémenté
PLAYLIST_SHARE	true	Backend implémenté
PLAYLIST_RECOMMENDATIONS	false	Backend pas implémenté
HLS_STREAMING	false	Backend NOT IMPLEMENTED
ROLE_MANAGEMENT	false	Backend NOT IMPLEMENTED
NOTIFICATIONS	true	Backend implémenté

Parcours utilisateur complets

1. Inscription → Vérification email → Connexion → Dashboard : complet
2. Connexion → Bibliothèque → Upload track → Détail track : complet (MSW)
3. Connexion → Recherche → Résultats → Lecture : complet (MSW)
4. Connexion → Playlists → Création → Ajout de tracks → Collaboration : complet (MSW)
5. Connexion → Chat → Conversations → Envoi messages : complet (MSW)
6. Connexion → Settings → Profil / Sécurité / Sessions : complet (MSW)
7. Connexion → Social → Feed → Posts : complet (MSW)

Parcours cassés

1. Connexion → Gear : se termine sur ComingSoon
2. Connexion → Live : se termine sur ComingSoon
3. Connexion → Education : se termine sur ComingSoon — pourtant 76 fichiers de composants studio existent dans components/studio/
4. Connexion → Marketplace → Achat : le flow checkout n'est pas confirmé côté backend
5. 2FA Login Verification : TODO critique dans TwoFactorVerify.tsx:47 — le service appelé est celui du setup, pas celui de la vérification login

Incohérences produit/code

• 76 fichiers studio existent dans components/studio/ mais aucune route /studio n'est définie
• Education a un service (educationService.ts), des handlers MSW complets (courses, enrollments), des composants (components/education/) mais est gated derrière ComingSoon
• Gamification (achievements, leaderboard, XP) a des handlers MSW mais aucune route ni composant visible
• Inventory/Gear a des composants (features/inventory/, components/inventory/) et des handlers MSW mais est gated derrière ComingSoon

---

5. AUDIT ACCESSIBILITÉ (WCAG 2.1 AA)

Perception

Critère	Verdict	Détail
Contrastes	Correct	Les tokens SUMI définissent des couleurs avec bon contraste dark/light
Alt text images	Correct	TrackCard utilise alt={Cover de ${track.title}}, Avatar a fallback
Contenu sans couleur	Non vérifié	Badges utilisent couleurs + texte (OK)
Mode réduit	Correct	prefers-reduced-motion respecté dans index.css (l.869-873)

Opérabilité

Critère	Verdict	Sévérité
Navigation clavier	Bonne	RadioGroup, Dropdown, Dialog ont keyboard nav
Focus visible	Bon	focus-visible:ring-2 systématique
Skip link	Présent	Lien dans App.tsx (href="#main-content", sr-only focus:not-sr-only)
Focus trap modals	Présent	FocusTrap component utilisé
Focus trap sidebar mobile	Absent	Majeure — sidebar mobile n'a pas de focus trap

Compréhension

Critère	Verdict	Sévérité
Labels formulaires	Partiel	Input/Textarea ont labels, ChatInput n'a pas d'aria-label
Messages erreur	Partiel	Input a aria-describedby, ChatInput non
Langue HTML	Non vérifié	Dépend de index.html
Instructions	Correct	HelpText component existe

Robustesse

Critère	Verdict	Détail
HTML sémantique	Bon	<article>, <aside>, <nav>, <header>, <main> utilisés
Rôles ARIA	Corrects	role="dialog", role="alert", role="switch", etc.
Landmarks	Bon	Sidebar (<aside>), Header (<header>), Navigation (<nav>)
Composants custom	Bon	RadioGroup, Tabs, Accordion suivent les patterns WAI-ARIA

Violations classées

Violation	Sévérité	Fichier
Skip link	Corrigé	Lien présent dans App.tsx
ChatInput sans aria-label	Majeure	features/chat/components/ChatInput.tsx
Sidebar mobile sans focus trap	Majeure	components/layout/Sidebar.tsx
MiniPlayer sans aria-live pour changement de track	Mineure	features/player/components/MiniPlayer.tsx
Sidebar status indicator aria-hidden contient du texte	Mineure	components/layout/Sidebar.tsx:136

---

6. ARCHITECTURE FRONTEND

Patterns & Qualité du code

Séparation logique métier / UI : Bonne. Les hooks (usePlayer, useChat, useAuth) encapsulent la logique. Les composants sont principalement présentationnels. Les services gèrent l'API.

Custom hooks : Bien découpés dans l'ensemble. 41 hooks dans hooks/ + hooks par feature. Quelques hooks complexes (usePlaylistCollaboration, usePlaylistKeyboardShortcuts) qui pourraient être décomposés.

State management :

• Local : React state pour l'UI locale (correct)
• Global : Zustand pour l'auth, UI, cart, rate limiting (correct)
• Server : React Query pour les données API (correct)
• Persistance : Zustand persist + broadcast sync cross-tab (avancé)

Props drilling : Modéré. Certains composants comme CourseLearningView passent 20+ props. Le pattern "composition + context" serait préférable dans 3-4 cas.

Re-renders :

• DashboardPage.tsx : arrays d'objets recréés à chaque render (l.66-71, l.131-164, l.300-304) — manque de useMemo
• TrackCard est correctement mémorisé avec React.memo (l.200)
• MiniPlayer : handlePlayPause recréé à chaque render (l.39-45) — mineur car composant léger

TypeScript : strict: true activé avec toutes les options. Mais @typescript-eslint/no-explicit-any: off dans ESLint — contredit la strictness. Résultat : any utilisé dans des services critiques (authService.ts l.35, l.54).

Side effects : Cleanup manquant sur setTimeout dans :

• ChatInput.tsx:106 — timeout sans cleanup
• SocialViewFeedItem.tsx:25,31 — setTimeout en callback sans ref
• PostCard.tsx:94,101 — même pattern

Couplage & Modularité

Cross-feature imports : Aucun trouvé. Les features sont correctement isolées.

Design system couplage : Faible — les composants UI sont indépendants. Changer un token dans index.css se propage correctement.

Backend couplage : Le code frontend est partiellement découplé grâce à MSW. Tous les services passent par apiClient. Cependant, les types API sont partiellement générés (types/generated/) et partiellement manuels — source d'incohérences potentielles.

Scalabilité

• Ajout d'une feature : faisable sans toucher plus de 3-4 fichiers (route, lazy export, feature directory, MSW handler)
• Changement de state management : modéré — Zustand est utilisé dans ~11 stores mais bien encapsulé derrière des hooks
• Extraction du design system : possible — les tokens sont dans index.css, les composants dans components/ui/. Le découplage est suffisant.
• Scaling 10x pages : possible — le lazy loading par route et le code splitting sont en place

---

7. DETTE TECHNIQUE DÉTAILLÉE

Dette critique (bloquante)

Item	Fichier(s)	Impact	Effort
Bug 2FA login vs setup	features/auth/components/TwoFactorVerify.tsx:47	Authentification 2FA potentiellement cassée en production	S
swagger-ui-react en dépendance production	package.json	Corrigé : en devDependencies	—
rollup-plugin-visualizer en dependencies	package.json	Corrigé : en devDependencies	—
any dans authService login/register	services/authService.ts:35,54	Pas de validation de types sur l'authentification	S
setTimeout sans cleanup	ChatInput.tsx:106, SocialViewFeedItem.tsx:25,31, PostCard.tsx:94,101	Memory leaks / state updates après unmount	S

Dette structurante

Item	Fichier(s)	Impact	Effort
3 composants de loading (Spinner, LoadingSpinner, LoadingState)	components/ui/	Confusion, incohérence visuelle	M
Modal deprecated non migré (6 imports restants)	components/ui/modal.tsx	Deux systèmes de modales coexistent	M
Composants feature dans components/ au lieu de features/	components/admin/, components/social/, components/studio/, components/settings/ etc.	Ambiguité structurelle sur où trouver le code	L
ErrorDisplay non testé	components/ui/ErrorDisplay.tsx	Corrigé : ErrorDisplay.test.tsx présent	—
Double système typographique (SUMI classes + Tailwind direct)	Toute la codebase	Incohérence dans l'usage	L
76 fichiers studio sans route	components/studio/	Code mort ou feature orpheline	M
console.log dans GlobalSearchBar (16 occurrences)	components/search/GlobalSearchBar.tsx	Logs en production	S
as unknown as assertions (15 occurrences)	Services divers	Contournement TypeScript	M
Stories manquant Loading/Error/Empty states	Majorité des stories	Contrat Storybook non respecté	L
noUncheckedIndexedAccess commenté dans tsconfig.app.json	tsconfig.app.json	~234 erreurs potentielles non détectées	L

Dette cosmétique

Item	Fichier(s)	Impact	Effort
~26 TODO/FIXME non résolus	Fichiers divers	Maintenance	S
Gamification handlers MSW sans UI	mocks/handlers.ts	Code mort	S
ComingSoon.tsx / AnimatedNumber.tsx non testés	components/ui/	Corrigé : tests présents	—

---

8. SCORES

Critère	Score /10	Justification
Architecture frontend	7.5	Feature-based bien exécuté, lazy loading, séparation des concerns. Points perdus : duplication components/features, scalabilité prouvée mais non testée à l'échelle.
Qualité du design system	8.0	Tokens SUMI exceptionnellement complets (couleurs, typo, espacement, motion, glass). Points perdus : double système typo, consommation incohérente des tokens, ~100 valeurs arbitraires.
Cohérence visuelle	7.0	Classes utilitaires SUMI bien définies, pas de !important abusif, cn() systématique. Points perdus : 3 composants loading, modal deprecated, FreeSans vs design tokens dans quelques composants.
Accessibilité	6.5	Bonne base (ARIA roles, focus visible, semantic HTML, keyboard nav, reduced motion). Points perdus : pas de skip link, ChatInput sans labels, sidebar mobile sans focus trap.
Performance perçue	7.5	Lazy loading routes, Skeleton screens, React Query cache, code splitting. Points perdus : pas d'optimistic updates systématiques, images non optimisées (pas de srcset), DashboardPage re-renders.
Maintenabilité	7.0	TypeScript strict, bonne couverture tests/stories, hooks bien découpés. Points perdus : any dans services critiques, cleanup manquants, console.log en production, double système typo.
Couverture de test frontend	7.5	~287 fichiers tests, ~323 stories. ErrorDisplay, LoadingState, Accordion, Collapsible, FAB, ComingSoon, AnimatedNumber ont des tests. Points perdus : stories sans Loading/Error/Empty, éventuels échecs tests tracks.
Scalabilité	7.0	Structure extensible, features découplées, no cross-imports. Points perdus : déjà trop de surface pour le backend actuel, components/ vs features/ ambiguité.
Expérience développeur (DX)	7.5	Path aliases, MSW complet, Storybook, ESLint flat config avec rules custom Tailwind. Points perdus : 55+ fichiers docs d'audit (bruit), lack of contributing guide, no ADR format.

Score global pondéré : 6.8/10

Le score est tiré vers le bas par le décalage backend/frontend (features affichées mais non câblées), les 42% de tests en échec, et les quelques failles d'accessibilité majeures.

---

9. RISQUES BUSINESS

Perspective Designer

Un designer peut travailler avec ce design system. Les tokens SUMI sont complets, documentés, et la documentation design (DESIGN_TOKENS.md, DESIGN_SYSTEM_REFERENCE.md) est exploitable. Le risque : la coexistence de deux systèmes typographiques (SUMI classes vs Tailwind direct) créera des incohérences si le designer spécifie des styles sans connaître cette dualité.

Perspective Développeur Frontend

Un développeur peut être productif en 3-5 jours grâce à la structure claire, les path aliases, MSW, et Storybook. Le risque : l'ambiguité components/ vs features/ ralentira la prise en main. Les 55+ fichiers d'audit dans docs/ sont du bruit qui noie la documentation utile (5 fichiers core).

Perspective Utilisateur Final

L'expérience est cohérente et fluide sur les parcours principaux (auth, library, tracks, playlists, chat). Le player fonctionne bien. Le risque : 5 routes "Coming Soon" donnent une impression d'inachevé. Le bug 2FA potentiel est bloquant pour la sécurité. Skip link présent (App.tsx).

Perspective Investisseur

Le frontend donne l'impression d'un produit mature en démo superficielle — le design SUMI est cohérent, l'architecture est professionnelle, les features affichées sont nombreuses. Le risque : en creusant, 5 routes sur 25 sont des placeholders, 6 features sont gated, le backend ne couvre pas toutes les promesses UI. L'investisseur averti posera la question : "pourquoi autant de surface frontend si le backend n'est pas prêt ?"

Réponses directes

• Ce frontend est-il présentable en démo ? Oui, sur les parcours auth → dashboard → library → tracks → playlists → chat → settings. Ne pas montrer gear/live/education/queue/developer.
• Ce design system est-il exploitable par une équipe ? Oui, avec un onboarding de 2-3 jours et la résolution de la dualité typographique.
• Le frontend peut-il absorber 6 mois d'évolution ? Oui, si on nettoie la dette structurante (M effort). L'architecture est extensible.
• Faut-il refactorer ou réécrire ? Refactorer. La base est saine. La réécriture serait un gaspillage disproportionné.

---

10. PLAN D'ACTION PRIORISÉ

Phase 1 — Urgences (1-2 semaines)

Action	Effort	Fichier(s)
Corriger bug 2FA login vs setup	S	features/auth/components/TwoFactorVerify.tsx:47
Déplacer swagger-ui-react en devDependencies	S	package.json
Déplacer rollup-plugin-visualizer en devDependencies	S	package.json
Supprimer 16 console.log dans GlobalSearchBar	S	components/search/GlobalSearchBar.tsx
Ajouter cleanup setTimeout dans ChatInput, SocialViewFeedItem, PostCard	S	3 fichiers
Ajouter skip link	—	Corrigé : lien dans App.tsx (href="#main-content")
Ajouter aria-label sur ChatInput	S	features/chat/components/ChatInput.tsx
Typer login/register dans authService (remplacer any)	S	services/authService.ts
Ajouter focus trap sidebar mobile	M	components/layout/Sidebar.tsx

Phase 2 — Consolidation (2-6 semaines)

Action	Effort	Fichier(s)
Unifier Spinner/LoadingSpinner/LoadingState en un seul composant	M	components/ui/ (3 fichiers)
Terminer migration Modal → Dialog (6 fichiers restants)	M	components/ui/modal.tsx + importeurs
Tests ErrorDisplay, LoadingState, Accordion, Collapsible, FAB, ComingSoon, AnimatedNumber	—	Corrigé : fichiers .test présents
Supprimer (track as any).like_count — étendre le type Track	S	features/tracks/components/TrackCard.tsx:43
Résoudre les 15 as unknown as dans les services	M	Services divers
Ajouter Loading/Error/Empty states aux stories existantes	L	~50+ stories
Unifier système typographique (SUMI classes uniquement ou Tailwind uniquement)	L	Codebase-wide
Auditer et réduire les ~100 valeurs arbitraires Tailwind en production	M	Fichiers identifiés
Memoiser arrays/callbacks dans DashboardPage	S	features/dashboard/pages/DashboardPage.tsx
Nettoyer components feature dans components/ (move vers features/)	L	components/admin/, social/, studio/, settings/
Fixer les 42% de tests en échec	L	Tests tracks et autres

Phase 3 — Maturité (6-12 semaines)

Action	Effort	Fichier(s)
Extraire design system SUMI en package npm indépendant	XL	components/ui/, index.css
Activer noUncheckedIndexedAccess dans tsconfig.app.json	L	tsconfig.app.json + ~234 fixes
Supprimer code fantôme (76 fichiers studio, handlers gamification) ou câbler au backend	L	components/studio/, mocks/handlers.ts
Ajouter CI visuel (visual regression tests)	M	Configuration
Ajouter aria-live regions pour contenu dynamique (player, notifications)	M	Player, Notifications
Documenter les patterns avec ADR (Architecture Decision Records)	M	docs/
Réduire les 55+ fichiers d'audit en docs/ à un CHANGELOG + KNOWN_ISSUES	S	docs/
Optimiser images (srcset, format WebP/AVIF, lazy loading natif)	M	Composants images
Améliorer code splitting (framer-motion, axios, DOMPurify en chunks séparés)	S	vite.config.ts

---

11. CONCLUSION STRATÉGIQUE

Verdict : REFACTORING CIBLÉ — ne pas réécrire.

Ce frontend possède une base architecturale solide : feature-based organization sans cross-imports, React Query + Zustand bien séparés, Tailwind v4 avec un design system tokens complet, lazy loading systématique, MSW exhaustif, TypeScript strict. C'est le travail d'un développeur (ou d'une petite équipe) compétent qui a construit vite et large.

Le problème n'est pas la qualité du code — c'est la dispersion. Le frontend couvre plus de surface que le backend ne peut supporter : 5 routes Coming Soon, 6 feature flags désactivés, 76 fichiers studio orphelins, des handlers MSW pour des features fantômes (gamification, inventory). Cela crée une illusion de complétude qui ne résiste pas à l'examen.

Recommandation pour un comité d'investissement :

1. Le frontend est exploitable — il ne nécessite pas de réécriture
2. La dette est gérable — Phase 1 (urgences) est réalisable en 1-2 semaines par un seul développeur
3. Le risque principal est stratégique — trop de features affichées sans backend. Recommander de geler toute nouvelle feature frontend jusqu'à parité backend
4. L'accessibilité a des lacunes majeures — 3 violations WCAG majeures à corriger avant toute mise en production
5. L'investissement en design system est un atout — SUMI v2.0 est exploitable par une équipe et extractible en package indépendant à moyen terme

Priorité absolue : corriger le bug 2FA, nettoyer les console.log, et fixer les tests en échec. Skip link et tests UI critiques (ErrorDisplay, LoadingState, ComingSoon, etc.) sont en place. Mise à jour 13/02/2026.