# Architecture Frontend Veza (React)

> Application web SPA + PWA avec support desktop Electron.
> Source : `apps/web/src/`

## Stack technique

| Composant | Technologie | Version |
|-----------|-------------|---------|
| Framework UI | React | 18 |
| Langage | TypeScript | strict |
| Build | Vite | 7.1.5 |
| CSS | Tailwind CSS | v4 |
| Composants | Radix UI + custom | |
| État global | Zustand | |
| Data fetching | TanStack Query (React Query) | |
| Formulaires | React Hook Form + Zod | |
| Routage | React Router | v6 |
| i18n | i18next | EN/FR/ES |
| Tests unitaires | Vitest | |
| Tests composants | Storybook | |
| Desktop | Electron (wrapper) | |

## Structure du projet

```
apps/web/src/
├── app/                   # Composant App + initialisation
├── components/            # Composants UI (36 sous-dossiers)
│   ├── admin/            # Panel admin
│   ├── auth/             # Guards + flows auth
│   ├── commerce/         # Marketplace, checkout
│   ├── dashboard/        # Widgets dashboard
│   ├── feedback/         # Toasts, notifications
│   ├── layout/           # Sidebar, Header, MainLayout
│   ├── marketplace/      # Affichage produits, panier
│   ├── modals/           # Dialogues modaux
│   ├── player/           # Lecteur audio
│   ├── search/           # Recherche, filtres
│   ├── social/           # Likes, follows
│   ├── upload/           # Upload de fichiers
│   └── ui/               # Composants de base (19 sous-dossiers)
├── features/              # Modules fonctionnels (38 sous-dossiers)
│   ├── admin/            # Fonctionnalité admin
│   ├── analytics/        # Stats, graphiques
│   ├── auth/             # Flows d'authentification
│   ├── chat/             # Chat temps réel
│   ├── commerce/         # Logique marketplace
│   ├── developer/        # Outils développeur
│   ├── library/          # Bibliothèque musicale
│   ├── live/             # Streaming live
│   ├── marketplace/      # Marketplace
│   ├── notifications/    # Notifications
│   ├── playlists/        # Gestion playlists
│   ├── player/           # Logique lecteur audio
│   ├── profile/          # Profil utilisateur
│   ├── settings/         # Paramètres
│   ├── social/           # Social
│   ├── streaming/        # Streaming audio
│   └── tracks/           # Gestion pistes
├── hooks/                 # Hooks React custom (46 fichiers)
├── router/                # Configuration routage
│   ├── routeConfig.tsx   # Définition des routes
│   ├── AppRouter.tsx     # Wrapper routeur
│   ├── ProtectedRoute.tsx # Guard authentification
│   └── PublicRoute.tsx   # Wrapper pages publiques
├── services/              # Clients API & logique métier
│   ├── api/              # Couche API REST
│   ├── websocket/        # Handlers WebSocket
│   └── storage/          # Storage local/session
├── stores/                # Stores Zustand
├── types/                 # Types TypeScript (9 fichiers)
├── utils/                 # Utilitaires (52 fichiers)
├── schemas/               # Schémas Zod (validation)
├── config/                # Configuration (env, URLs API)
├── context/               # Providers React Context
├── lib/                   # Intégrations tierces
│   ├── i18n.ts           # Configuration i18next
│   └── sentry.ts         # Sentry error tracking
├── locales/               # Traductions i18n
├── styles/                # Styles globaux
└── __tests__/             # Tests
```

## Routes de l'application

### Routes publiques (sans authentification)

| Route | Page | Description |
|-------|------|-------------|
| `/login` | Login | Page de connexion |
| `/register` | Register | Inscription |
| `/forgot-password` | ForgotPassword | Récupération mot de passe |
| `/verify-email` | VerifyEmail | Vérification email |
| `/reset-password` | ResetPassword | Reset avec token |
| `/` | Landing | Page d'accueil |
| `/discover` | Discover | Découverte publique |
| `/p/:playlistToken` | SharedPlaylist | Playlist partagée |

### Routes protégées (authentification requise)

| Route | Page | Description |
|-------|------|-------------|
| `/dashboard` | Dashboard | Feed principal |
| `/library` | Library | Bibliothèque musicale |
| `/settings/*` | Settings | Paramètres utilisateur |
| `/u/:username` | Profile | Profil utilisateur |
| `/playlist/:id` | PlaylistDetail | Détail playlist |
| `/track/:id` | TrackDetail | Détail piste |
| `/marketplace/*` | Marketplace | Pages marketplace |
| `/cart` | Cart | Panier |
| `/checkout` | Checkout | Paiement |
| `/chat` | Chat | Interface de chat |
| `/notifications` | Notifications | Notifications |
| `/analytics` | Analytics | Dashboard analytics |
| `/webhooks` | Webhooks | Gestion webhooks |
| `/admin/*` | Admin | Panel admin |
| `/search` | Search | Résultats recherche |
| `/social/*` | Social | Fonctionnalités sociales |
| `/live/*` | Live | Streaming live |
| `/seller/*` | Seller | Dashboard vendeur |
| `/developer/*` | Developer | Outils développeur |
| `/queue` | Queue | File d'attente |
| `/listen-together` | CoListening | Co-écoute |
| `/wishlist` | Wishlist | Liste de souhaits |
| `/purchases` | Purchases | Historique achats |

## Gestion d'état (Zustand)

### Stores principaux

```typescript
// UI State (stores/ui.ts)
{
  sidebarOpen: boolean,
  darkMode: boolean,
  activeModal: string | null,
}

// Library State (stores/library.ts)
{
  favorites: Track[],
  recentlyPlayed: Track[],
  playlists: Playlist[],
}

// Cart State (stores/cartStore.ts)
{
  items: CartItem[],
  total: number,
}

// Rate Limit State (stores/rateLimit.ts)
{
  remaining: number,
  resetTime: Date,
}
```

## Services API (`services/api/`)

| Fichier | Domaine | Exemples d'opérations |
|---------|---------|----------------------|
| `auth.ts` | Authentification | login, register, refresh, logout |
| `tracks.ts` | Pistes | CRUD, upload, search, like |
| `playlists.ts` | Playlists | CRUD, collaborators, share |
| `users.ts` | Utilisateurs | profil, follow, block, settings |
| `marketplace.ts` | Marketplace | products, orders, reviews |
| `search.ts` | Recherche | unified search, suggestions |
| `streaming.ts` | Streaming | intégration stream server |
| `chat.ts` | Chat | rooms, messages, reactions |
| `notifications.ts` | Notifications | list, preferences, push |
| `analytics.ts` | Analytics | stats, charts, export |

## Hooks personnalisés (`hooks/`)

| Hook | Usage |
|------|-------|
| `useUser()` | Données utilisateur courant |
| `useAuth()` | État d'authentification |
| `useTracks()` | Opérations sur les pistes |
| `usePlaylists()` | Opérations sur les playlists |
| `usePlayer()` | État du lecteur audio |
| `useSearch()` | Fonctionnalité recherche |
| `useChat()` | Opérations chat |
| `useNotifications()` | État notifications |
| `useLocalStorage()` | Persistance locale |
| `useQueryClient()` | Intégration TanStack Query |

46 hooks au total pour encapsuler la logique métier.

## Configuration

```typescript
// config/env.ts
export const env = {
  API_URL: import.meta.env.VITE_API_URL || '/api/v1',
  FRONTEND_URL: 'http://localhost:5173',
  USE_MSW: import.meta.env.VITE_USE_MSW === 'true',
  STORYBOOK: import.meta.env.VITE_STORYBOOK === 'true',
  SENTRY_DSN: import.meta.env.VITE_SENTRY_DSN,
}
```

### Variables d'environnement frontend

| Variable | Description |
|----------|-------------|
| `VITE_API_URL` | URL de l'API backend |
| `VITE_USE_MSW` | Activer les mocks MSW |
| `VITE_STORYBOOK` | Mode Storybook |
| `VITE_SENTRY_DSN` | DSN Sentry pour error tracking |

## Internationalisation (i18n)

- **Bibliothèque** : i18next
- **Langues** : Anglais (EN), Français (FR), Espagnol (ES)
- **Fichiers** : `src/locales/`
- **Détection** : Langue du navigateur automatique
- **Persistance** : localStorage

## Scripts de développement

```bash
# Développement avec hot reload
npm run dev                 # ou : make dev-web

# Développement avec API mockée (MSW)
npm run dev:mocks

# Build production
npm run build

# Tests
npm run test               # Vitest
npm run test:e2e           # E2E (au root du repo)

# Qualité
npm run lint               # ESLint
npm run typecheck           # TypeScript strict

# Storybook (catalogue composants)
npm run storybook          # Port 6006
npm run build-storybook
```

## Nginx (production)

En production, le frontend est servi par Nginx avec :
- **SPA routing** : Toutes les routes renvoient vers `index.html`
- **Proxy `/api`** → Backend Go (port 8080)
- **Proxy `/ws`** → Chat WebSocket (port 8081)
- **Proxy `/stream`** → Stream server (port 8082)
- **Compression gzip** activée
- **Cache headers** pour les assets statiques
- **Security headers** : X-Frame-Options, X-Content-Type-Options

Configuration : `apps/web/nginx.conf`

## Dockerfiles

| Fichier | Base | Usage |
|---------|------|-------|
| `Dockerfile` | `node:20-alpine` → `nginx:alpine` | Développement |
| `Dockerfile.production` | `nginx:latest` | Production |

## Desktop (Electron)

Le dossier `veza-desktop/` contient un wrapper Electron minimal qui charge `apps/web`. Pas d'application native séparée — le même code frontend est utilisé partout.

## Statistiques

| Métrique | Valeur |
|----------|--------|
| Composants UI | 661 |
| Routes | 52+ |
| Hooks custom | 46 |
| Utilitaires | 52 |
| Sous-dossiers features | 38 |
| Langues i18n | 3 (EN/FR/ES) |

## Documents liés

- [[ARCHITECTURE_VEZA]] — Architecture globale
- [[ROUTES_API]] — Endpoints API backend
- [[CONFIGURATION_ENVIRONNEMENT]] — Variables d'environnement