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

// 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

// 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)

Scripts de développement

# Développement avec hot reload {#developpement-avec-hot-reload}
npm run dev                 # ou : make dev-web

# Développement avec API mockée (MSW) {#developpement-avec-api-mockee-msw}
npm run dev:mocks

# Build production {#build-production}
npm run build

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

# Qualité {#qualite}
npm run lint               # ESLint
npm run typecheck           # TypeScript strict

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

Nginx (production)

En production, le frontend est servi par Nginx avec :

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