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.