veza/apps/web/dev_audit/frontend/01_architecture_analysis.md

# Phase A — Architecture Frontend Analysis

**Score Architecture : 7/10**

---

## A1. Structure des dossiers

### Organisation réelle

```
src/
├── app/          → Shell applicatif (App.tsx)
├── components/   → Composants partagés (30+ sous-dossiers)
├── config/       → Configuration (env, features flags)
├── context/      → React Context (AuthContext, AudioContext)
├── features/     → Modules feature-based (24 features)
├── hooks/        → Hooks partagés (~30 hooks)
├── lib/          → Init librairies (i18n, sentry)
├── locales/      → Traductions i18n
├── mocks/        → MSW handlers
├── pages/        → Pages legacy (auth, marketplace)
├── providers/    → AuthProvider
├── router/       → Routing centralisé
├── schemas/      → Schémas Zod
├── services/     → Services API (~35 services)
├── stores/       → Zustand stores partagés
├── stories/      → Storybook decorators
├── test/         → Test setup
├── types/        → Types globaux et générés
└── utils/        → Utilitaires (~25 fichiers)
```

### Séparation `features/` vs `components/`

**Positif** : La codebase utilise un pattern feature-based dans `features/` avec des modules autonomes contenant chacun `api/`, `components/`, `hooks/`, `services/`, `store/`, `pages/`. [features/auth/store/authStore.ts], [features/playlists/hooks/usePlaylist.ts], [features/tracks/api/trackApi.ts]

**Problème majeur** : **Dualité non résolue** entre :
- `components/views/` (analytics-view, cart-view, chat-view, discover-view, etc. — ~20 vues) et `features/*/pages/` — deux patterns coexistent pour le même rôle [components/views/analytics-view/], [features/dashboard/pages/]
- `pages/auth/` (Login.tsx, Register.tsx) et `features/auth/pages/` (LoginPage.tsx, RegisterPage.tsx) — **duplication directe** [pages/auth/Login.tsx vs features/auth/pages/LoginPage.tsx]
- `context/AuthContext.tsx` et `features/auth/store/authStore.ts` — **deux sources de vérité pour l'auth** [context/AuthContext.tsx:54, features/auth/store/authStore.ts:55]
- `providers/AuthProvider.tsx` et `context/AuthContext.tsx` — coexistence redondante

### Barrel exports (`index.ts`)

**Présents et cohérents** dans les feature views refactorées :
- `components/views/analytics-view/index.ts` ✅
- `components/views/cart-view/index.ts` ✅
- `components/views/settings-view/index.ts` ✅
- `features/*/index.ts` — **absents** dans la plupart des features ❌

### Routes colocalisées

Les routes sont centralisées dans `router/routeConfig.tsx` [routeConfig.tsx:57-109], pas colocalisées avec les features. C'est un choix acceptable pour un projet de cette taille, mais limite la découvrabilité.

### Dossiers morts ou orphelins

- `pages/auth/` — **probablement orphelin** : contient Login.tsx et Register.tsx mais les routes pointent vers `features/auth/pages/` via LazyComponent [routeConfig.tsx:59-63]
- `components/views/*.tsx` (fichiers plats type `AnalyticsView.tsx`, `CartView.tsx`) — semblent être des **wrappers legacy** vers les sous-dossiers refactorés
- `stories/` — contient uniquement `decorators.tsx`, pourrait être dans `.storybook/`

**Verdict structure** : Organisation feature-based ambitieuse mais migration incomplète. La dualité `components/views/` vs `features/*/pages/` et les vestiges legacy (`pages/`, `context/AuthContext.tsx`) créent de la confusion. **-2 points.**

---

## A2. Séparation des responsabilités

### Composants > 100 lignes (source, hors tests)

| Composant | Lignes | Type | Responsabilités mélangées ? | Verdict |
|-----------|--------|------|----------------------------|---------|
| `services/api/client.ts` | 2 237 | Service | API client + validation + caching + retry + dedup + metrics | ❌ Monolithe |
| `features/tracks/api/trackApi.ts` | 848 | Service | CRUD tracks + upload + share + analytics | ⚠️ Large mais cohérent |
| `utils/optimisticUpdates.ts` | 682 | Utilitaire | Optimistic updates multi-feature | ⚠️ Acceptable |
| `features/streaming/services/playbackAnalyticsService.ts` | 656 | Service | Analytics streaming | ⚠️ Complexité justifiée |
| `features/playlists/hooks/usePlaylist.ts` | 631 | Hook smart | CRUD + collaboration + analytics | ❌ Trop de responsabilités |
| `utils/apiErrorHandler.ts` | 578 | Utilitaire | Error parsing + categorization | ⚠️ Acceptable |
| `features/streaming/hooks/usePlaybackRealtime.ts` | 496 | Hook smart | WebSocket + state + analytics | ⚠️ Justifié par temps réel |
| `services/api/auth.ts` | 493 | Service | Auth API complète | ⚠️ Cohérent |
| `schemas/apiRequestSchemas.ts` | 476 | Types | Schémas Zod | ✅ Naturellement grand |
| `schemas/apiSchemas.ts` | 468 | Types | Schémas Zod | ✅ Naturellement grand |
| `features/tracks/services/trackService.ts` | 453 | Service | Service tracks | ⚠️ Cohérent |
| `features/playlists/services/playlistService.ts` | 448 | Service | Service playlists | ⚠️ Cohérent |
| `utils/sanitize.ts` | 429 | Utilitaire | Sanitization XSS | ✅ Sécurité critique |

**Point critique** : `client.ts` (2237L) est un **God Object**. Il cumule : instance Axios, interceptors, validation Zod, caching, request deduplication, metrics tracking, offline queue, rate limiting, CSRF. Il devrait être éclaté en 4-5 modules. [services/api/client.ts:1-80]

**Positif** : La séparation services/hooks/components est généralement respectée dans les features refactorées (auth, playlists, tracks, streaming).

---

## A3. Gestion d'état

### Couches identifiées

**1. Zustand Stores (7 stores)** :

| Store | Fichier | Contenu | Persisté | Sync tabs |
|-------|---------|---------|----------|-----------|
| `authStore` | `features/auth/store/authStore.ts` | isAuthenticated, isLoading, error | ✅ localStorage | ✅ broadcastSync |
| `uiStore` | `stores/ui.ts` | theme, language, sidebarOpen, notifications | ✅ localStorage | ✅ broadcastSync |
| `cartStore` | `stores/cartStore.ts` | items, actions CRUD | ✅ localStorage | ❌ |
| `playerStore` | `features/player/store/playerStore.ts` | Playback state | Probable | À vérifier |
| `chatStore` | `features/chat/store/chatStore.ts` | Chat state | À vérifier | À vérifier |
| `libraryStore` | `stores/library.ts` | Library state | À vérifier | À vérifier |
| `rateLimitStore` | `stores/rateLimit.ts` | Rate limit tracking | ❌ | ❌ |

**2. React Query (TanStack Query v5)** — Server state principal :
- Utilisé dans ~30+ fichiers [features/playlists/hooks/usePlaylist.ts, features/tracks/components/LikeButton.tsx, etc.]
- `useQuery` pour lectures, `useMutation` pour écritures
- Optimistic updates via `utils/optimisticUpdates.ts` [utils/optimisticUpdates.ts]
- Cache sync cross-tabs via `utils/reactQuerySync.ts` [app/App.tsx:47-54]
- QueryClient config : `staleTime: 1min`, `gcTime: 5min`, `retry: false` [main.tsx:43-55]

**3. React Context (4 contextes)** :
- `AuthContext` [context/AuthContext.tsx] — **CONFLIT** avec `authStore` : deux sources de vérité pour l'auth
- `AudioContext` [context/audio-context/AudioContext.tsx] — contexte audio player
- `ThemeProvider` [components/theme/ThemeProvider.tsx] — thème (mais aussi géré par uiStore)
- `ToastProvider` [components/feedback/ToastProvider.tsx] — gestion toasts

**4. State local (useState)** — usage standard dans les composants

### Diagnostique

**Conflit critique** : `AuthContext` [context/AuthContext.tsx:54] utilise `authService` directement avec `useState` pour `user`, tandis que `authStore` [features/auth/store/authStore.ts:55] utilise Zustand avec `loginService` et gère `isAuthenticated` sans `user` (délégué à React Query). **L'App.tsx utilise `authStore`** [app/App.tsx:4], mais `AuthContext` existe toujours et pourrait être importé par erreur. → **Source de bugs potentiels.**

**Duplication thème** : Le thème est géré par `uiStore` [stores/ui.ts:35-51] ET `ThemeProvider` [components/theme/ThemeProvider.tsx]. L'App.tsx applique le thème via `uiStore` [app/App.tsx:80-94].

**Prop drilling** : Minimisé grâce à Zustand + React Query. Pas de chaîne > 3 niveaux identifiée dans le code audité.

---

## A4. Gestion des requêtes réseau

### Architecture réseau

Le projet utilise un **client Axios centralisé** dans `services/api/client.ts` [services/api/client.ts:1-80] qui fournit :
- Interceptors pour JWT (Authorization header) [client.ts:9]
- Refresh token automatique [client.ts:10]
- Validation Zod des requêtes et réponses [client.ts:24-25]
- Request deduplication [client.ts:21]
- Response caching [client.ts:22]
- Offline queue [client.ts:20]
- Rate limiting tracking [client.ts:27]
- CSRF protection [client.ts:14]
- Validation metrics [client.ts:33-41]

### Patterns observés

| Fichier | Méthode | Loading | Error | Cancel | Typé | Centralisé |
|---------|---------|---------|-------|--------|------|------------|
| `features/tracks/api/trackApi.ts` | Axios client | Via React Query | Via React Query | Via React Query | ✅ Zod | ✅ |
| `services/api/auth.ts` | Axios client | Manual/Store | ✅ parseApiError | ❌ | ✅ Zod | ✅ |
| `features/playlists/services/playlistService.ts` | Axios client | Via hooks | ✅ | ❌ | ✅ | ✅ |
| `services/websocket.ts` | WebSocket natif | ❌ | ✅ reconnect | N/A | ⚠️ `any` (8x) | ✅ |
| `context/AuthContext.tsx` | authService direct | ✅ useState | ✅ toast | ❌ | ❌ `any` (4x) | ⚠️ Parallèle |

**Positif** : Architecture réseau très mature avec dedup, caching, offline queue, validation Zod end-to-end, CSRF. C'est au-dessus de la moyenne.

**Négatif** : Le client.ts est un monolithe de 2237L qui concentre trop de responsabilités. L'AbortController n'est pas systématiquement utilisé pour annuler les requêtes au démontage.

---

## A5. Routing

- **Solution** : React Router DOM v6.22 [package.json]
- **Routes protégées** : `ProtectedRoute` component wrapper [routeConfig.tsx:47-55] + `ProtectedLayoutRoute` pour le layout dashboard
- **Lazy loading** : ✅ Toutes les routes sont lazy via `LazyComponent` [routeConfig.tsx:5-33] — pattern `React.lazy` centralisé
- **404** : ✅ `LazyNotFound` route + catch-all `*` → `/404` [AppRouter.tsx:30-31]
- **500** : ✅ `LazyServerError` route [routeConfig.tsx:107]
- **Deep linking** : ✅ Routes paramétrées (`/tracks/:id`, `/u/:username`, `/playlists/*`) [routeConfig.tsx:87-88]
- **ComingSoon** : Routes planifiées mais non implémentées utilisent un placeholder `ComingSoon` [routeConfig.tsx:96-101] — propre
- **v7 migration** : Flags de préparation activés `v7_startTransition`, `v7_relativeSplatPath` [main.tsx:221-222]

**Verdict routing** : Solide, bien structuré, lazy loading systématique. **+1 point.**

---

## A6. Gestion des erreurs

### Error Boundaries

- **Root level** : `ErrorBoundary` wrapping `App` [app/App.tsx:171]
- **Route level** : Chaque route wrappée dans `ErrorBoundary` [routeConfig.tsx:40-55]
- **Composant** : `ErrorBoundary` class component avec UI de fallback, retry et go-home [components/ui/ErrorBoundary.tsx:16-77]
- **Fallback configurable** : ✅ via prop `fallback` [ErrorBoundary.tsx:13]

### Erreurs réseau

- `parseApiError` centralisé [utils/apiErrorHandler.ts] — 578L, parsing exhaustif des erreurs Axios
- `formatUserFriendlyError` [utils/errorMessages.ts] — messages user-friendly
- Toast pour feedback utilisateur [utils/toast.ts]
- Rate limit indicator [components/RateLimitIndicator.tsx]
- Offline indicator [components/OfflineIndicator.tsx]

### Logging

- Sentry intégré [lib/sentry.ts, main.tsx:28,41]
- Logger structuré custom [utils/logger.ts] avec niveaux et contexte

### Fallback UI

- Error states avec `ErrorDisplay` component [components/ui/ErrorDisplay.tsx]
- Loading states avec spinners et skeletons (chaque view a un Skeleton)
- Empty states gérés dans les features refactorées

**Verdict erreurs** : Gestion des erreurs très complète — error boundaries, parsing centralisé, Sentry, toasts, offline detection. **+1 point.**

---

## Score Architecture détaillé

| Critère | Points | Justification |
|---------|--------|---------------|
| Structure feature-based | +2 | Organisation claire en features avec séparation concerns |
| Migration incomplète | -2 | Dualité components/views vs features/pages, fichiers legacy |
| State management | +1.5 | Zustand + React Query bien intégré, sync cross-tabs |
| Conflit AuthContext vs authStore | -1 | Deux sources de vérité pour l'auth |
| Client API centralisé | +1.5 | Validation Zod, dedup, caching, offline queue |
| client.ts monolithe | -0.5 | 2237L, trop de responsabilités |
| Routing | +1.5 | Lazy loading systématique, 404/500, guards |
| Error handling | +1.5 | ErrorBoundary, Sentry, toast, offline indicator |
| Barrel exports partiels | -0.5 | Incohérents entre features et components |
| TypeScript strict | +1 | Mode strict complet avec noUncheckedIndexedAccess |
| **Total** | **7/10** | **Solide, mais dette structurelle de migration** |

**Résumé** : L'architecture est ambitieuse et globalement solide, avec des patterns modernes (feature-based, server state séparé, validation Zod). Le principal problème est la migration incomplète qui laisse coexister deux patterns architecturaux (`components/views/` vs `features/pages/`, `AuthContext` vs `authStore`). Le client HTTP centralisé est puissant mais devenu un monolithe à découper.