287 lines
9.7 KiB
Markdown
287 lines
9.7 KiB
Markdown
|
# 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
|