veza/apps/web/dev_audit/frontend/00_frontend_overview.md

Phase 0 — Frontend Overview

Date : 2026-02-12 Auditeur : Audit automatisé exhaustif Scope : apps/web/src/ exclusivement

---

Statistiques brutes

Répartition des fichiers

Type	Nombre
.tsx	1 450
.ts	621
.css	5
.scss	0
.module.css	0
.svg	5
Total fichiers	2 081
LOC total	~218 500

Fichiers > 300 lignes (source uniquement, hors tests)

Fichier	Lignes	Nature
src/types/generated/api.ts	7 123	Types auto-générés OpenAPI
src/services/api/client.ts	2 237	Client HTTP centralisé
src/mocks/handlers.ts	1 716	MSW mock handlers
src/features/tracks/api/trackApi.ts	848	API tracks
src/utils/optimisticUpdates.ts	682	Logique optimistic updates
src/features/streaming/services/playbackAnalyticsService.ts	656	Analytics streaming
src/features/playlists/hooks/usePlaylist.ts	631	Hook playlist principal
src/utils/apiErrorHandler.ts	578	Gestion erreurs API
src/features/streaming/hooks/usePlaybackRealtime.ts	496	Hook streaming temps réel
src/services/api/auth.ts	493	Service auth API
src/schemas/apiRequestSchemas.ts	476	Schémas Zod requêtes
src/schemas/apiSchemas.ts	468	Schémas Zod réponses
src/features/tracks/services/trackService.ts	453	Service tracks
src/features/playlists/services/playlistService.ts	448	Service playlists
src/utils/sanitize.ts	429	Sanitization XSS

Observations :

• 15 fichiers source > 400 lignes (hors tests/generated). Les plus critiques sont client.ts (2237L) et trackApi.ts (848L).
• Les fichiers de tests sont nombreux à dépasser 400L (ex: TrackUpload.test.tsx 783L, playlistService.test.ts 780L), signe de tests relativement exhaustifs.
• Le fichier api.ts généré (7123L) est attendu pour des types OpenAPI.

---

Stack détectée

Couche	Technologie	Version
Framework	React	18.2.x
Bundler	Vite	7.1.x
Langage	TypeScript	5.3.x (strict mode complet)
CSS	Tailwind CSS	v4.0 (CSS-first config)
Design System	SUMI v2.0	Custom, CSS variables
State global	Zustand	4.5.x
Server state	TanStack React Query	5.17.x
Routing	React Router DOM	6.22.x
Formulaires	React Hook Form + Zod	7.49.x / 3.25.x
Animation	Framer Motion	12.29.x
HTTP	Axios	1.13.x
i18n	i18next + react-i18next	25.5.x / 15.7.x
Monitoring	Sentry	10.32.x
Icônes	Lucide React	0.321.x
Tests unitaires	Vitest	3.2.x
Tests E2E	Playwright	1.58.x
Storybook	Storybook	8.6.x
Mocking	MSW	2.11.x
Linting	ESLint 9 (flat config) + Prettier	9.x / 3.2.x
Accessibility	eslint-plugin-jsx-a11y	6.10.x
Virtualisation	TanStack Virtual	3.13.x
DnD	@dnd-kit	6.3.x
Toast	react-hot-toast	2.6.x

---

Dépendances notables

Production (critiques)

• dompurify 3.3.x — sanitization HTML (bon signe sécurité)
• hls.js 1.6.x — streaming HLS
• immer 10.x — immutabilité state
• zod 3.25.x — validation schemas
• emoji-picker-react 4.16.x — feature chat
• swagger-ui-react 5.31.x — documentation API embarquée

Dev (notables)

• @storybook/addon-a11y — audit accessibilité intégré
• pa11y-ci — CI accessibility testing
• backstopjs — visual regression testing
• pixelmatch / pngjs — visual diff
• storybook-dark-mode — dark mode Storybook
• tw-animate-css — animations Tailwind

---

Arborescence commentée (2 niveaux)

src/
├── app/                    # Point d'entrée App, shell principal
├── components/             # Composants partagés (UI, layout, domain)
│   ├── admin/              # Vues administration
│   ├── analytics/          # Composants analytics
│   ├── auth/               # Composants auth (ProtectedRoute)
│   ├── charts/             # Composants graphiques
│   ├── commerce/           # Cart, wishlist
│   ├── dashboard/          # Dashboard widgets
│   ├── developer/          # Swagger UI, API keys
│   ├── education/          # Cours, learning
│   ├── feedback/           # Toast, progress
│   ├── filters/            # Filtres, tri
│   ├── forms/              # Form primitives
│   ├── gamification/       # XP, achievements
│   ├── inventory/          # Inventaire
│   ├── keyboard/           # Raccourcis clavier
│   ├── layout/             # DashboardLayout, Sidebar, Header, Navbar
│   ├── library/            # Playlists, watermark
│   ├── live/               # Live streaming
│   ├── marketplace/        # Marketplace cards
│   ├── modals/             # Modales partagées
│   ├── monitoring/         # Monitoring dashboard
│   ├── navigation/         # Breadcrumbs
│   ├── notifications/      # Notification bell/menu
│   ├── player/             # Audio player UI
│   ├── pwa/                # PWA composants
│   ├── search/             # Search bar, results
│   ├── seller/             # Seller dashboard
│   ├── settings/           # Settings views
│   ├── share/              # Sharing
│   ├── social/             # Social feed, groups
│   ├── studio/             # Studio projects
│   ├── theme/              # Theme provider, switcher
│   ├── ui/                 # ⭐ Primitives UI (button, input, dialog, etc.)
│   ├── upload/             # Upload components
│   ├── user/               # User profile components
│   └── views/              # Feature views (analytics, cart, chat, etc.)
├── config/                 # Configuration (env, features flags)
├── context/                # React Context (AuthContext)
├── features/               # ⭐ Feature modules (domain-driven)
│   ├── admin/              # Admin feature
│   ├── analytics/          # Analytics feature
│   ├── auth/               # Auth (login, register, 2FA, OAuth)
│   ├── chat/               # Chat feature
│   ├── dashboard/          # Dashboard feature
│   ├── error/              # Error pages
│   ├── inventory/          # Inventory feature
│   ├── library/            # Library feature
│   ├── marketplace/        # Marketplace feature
│   ├── notifications/      # Notifications feature
│   ├── player/             # ⭐ Player (store, hooks, services, components)
│   ├── playlists/          # Playlists feature (CRUD, collab, analytics)
│   ├── profile/            # Profile feature
│   ├── roles/              # Role management
│   ├── search/             # Search feature
│   ├── sessions/           # Sessions management
│   ├── settings/           # Settings feature
│   ├── stream/             # Stream feature
│   ├── streaming/          # Streaming (HLS, playback analytics)
│   ├── studio/             # Studio feature
│   ├── tracks/             # ⭐ Tracks (upload, comments, share, search)
│   ├── upload/             # Upload feature
│   ├── user/               # User feature
│   └── webhooks/           # Webhooks feature
├── hooks/                  # Hooks partagés (useAuth, useDebounce, etc.)
├── lib/                    # Librairies init (i18n, sentry)
├── locales/                # Fichiers de traduction i18n
├── mocks/                  # MSW handlers
├── pages/                  # Pages (auth, marketplace) — legacy?
├── providers/              # AuthProvider
├── router/                 # Routing (AppRouter, config, guards)
├── schemas/                # Schémas Zod (request/response validation)
├── services/               # Services API (REST, WebSocket, storage)
├── stores/                 # Zustand stores (cart, library, UI, rateLimit)
├── stories/                # Storybook decorators
├── styles/                 # (si fichiers CSS additionnels)
├── test/                   # Test utilities, setup
├── __tests__/              # Tests globaux (accessibility, contrast)
├── types/                  # Types globaux et générés
└── utils/                  # Utilitaires (sanitize, logger, toast, etc.)

---

Patterns critiques détectés

Pattern	Occurrences	Risque
dangerouslySetInnerHTML	2 fichiers	🟠 Moyen (chat)
localStorage/sessionStorage	~45 fichiers	🟡 Faible (encapsulé via safeStorage.ts, tokenStorage.ts)
eval() / new Function()	0	✅
console.log/debug/info	~27 fichiers	🟡 Faible (principalement dev/stories)
: any	~80+ fichiers	🟠 Moyen
as any	~100+ fichiers (dont 145 dans generated/api.ts)	🟠 Moyen
@ts-ignore / @ts-expect-error	7 fichiers	🟢 Faible
style={{}} inline	~80 fichiers	🟠 Moyen
TODO/FIXME/HACK	~20 occurrences	🟡 Normal

---

Variables d'environnement client (VITE_*)

Déclarées dans src/vite-env.d.ts [vite-env.d.ts:4-21] :

• VITE_API_URL, VITE_WS_URL, VITE_STREAM_URL, VITE_UPLOAD_URL — endpoints API
• VITE_APP_NAME — nom de l'application
• VITE_DEBUG, VITE_USE_MSW, VITE_STORYBOOK — flags dev
• VITE_FCM_VAPID_KEY — push notifications
• Feature flags : VITE_FEATURE_TWO_FACTOR_AUTH, VITE_FEATURE_PLAYLIST_*, VITE_FEATURE_HLS_STREAMING, VITE_FEATURE_ROLE_MANAGEMENT, VITE_FEATURE_NOTIFICATIONS

Fichiers .env présents :

• .env.example (2.2KB) — template
• .env.local (450B) — config locale
• .env.production (1.8KB) — config prod
• .env.storybook (262B) — config Storybook
• Attention : .env.local et .env.production sont versionnés (visibles). .gitignore ne semble pas exclure les fichiers .env.*.

---

Première impression architecturale

1. Architecture mature et ambitieuse : Le projet adopte une organisation feature-based (features/) combinée à des composants partagés (components/ui/, components/layout/), des services centralisés et un design system custom (SUMI v2.0). C'est un projet SaaS complet avec ~2000 fichiers et ~218K LOC — une codebase significative.

2. Stack moderne mais complexe : Tailwind v4 CSS-first, React 18, TanStack Query v5, Zustand, Zod, i18next, Sentry, MSW, Storybook 8.6, Playwright — l'outillage est complet mais la complexité d'intégration est élevée. Le main.tsx (273L) avec son waitForStylesheets et son preloading toast révèle des workarounds de stabilité.

3. Dualité préoccupante : Il existe une coexistence entre components/views/ (analytics-view, cart-view, etc.) et features/*/pages/ qui suggère une migration architecturale en cours ou incomplète. De même, pages/auth/ coexiste avec features/auth/pages/, et context/AuthContext.tsx avec providers/AuthProvider.tsx. Cette dualité est un signal de dette structurelle.