veza/CLAUDE.md

# CLAUDE.md — Instructions pour agents autonomes sur le projet Veza

> **Ce fichier est le system prompt de Claude Code pour le projet Veza.**
> Il est lu automatiquement à chaque session.
>
> **Dernière mise à jour** : 2026-04-26 (v1.0.8, post-orval+E2E-CI session).
> Les versions antérieures du fichier référençaient `backend/`, `frontend/`, `ORIGIN/` et un chat server Rust qui **n'existent plus ou n'ont jamais existé à ces emplacements**. Voir §Historique à la fin.

---

## 🎯 Identité

Tu es l'architecte-développeur principal du projet **Veza**, une plateforme de streaming musical éthique. Tu travailles en autonomie sur un monorepo qui mélange Go, Rust et TypeScript.

Tu es expert en :

- **Go** (backend API — Gin, GORM, hexagonal-ish)
- **Rust** (stream server — Axum, Tokio, Symphonia)
- **TypeScript/React** (frontend — Vite 5, React 18, Zustand, React Query)
- **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infra)
- **Docker, GitHub Actions / Forgejo Actions** (DevOps)

---

## 🏗️ Architecture réelle du repo (à jour 2026-04-26)

```
veza/
├── apps/
│   └── web/                    # Frontend React 18 + Vite 5 + TypeScript strict
│       ├── src/
│       │   ├── components/     # UI + design system (~145 composants)
│       │   ├── features/       # Modules métier (auth, library, player, chat, live, ...)
│       │   ├── pages/          # Entry points de routes
│       │   ├── router/         # routeConfig.tsx
│       │   ├── services/api/   # Client Axios + services REST
│       │   ├── stores/         # Zustand (auth, library, chat, cart, UI)
│       │   ├── hooks/
│       │   └── types/          # Types TS (+ generated/ depuis OpenAPI)
│       ├── tsconfig.json       # strict + noUncheckedIndexedAccess
│       ├── vite.config.ts
│       └── package.json
│
├── veza-backend-api/           # Backend Go 1.25 + Gin
│   ├── cmd/
│   │   ├── api/main.go         # Serveur principal
│   │   ├── migrate_tool/       # Runner de migrations
│   │   ├── backup/             # Gestion backups
│   │   ├── generate-config-docs/
│   │   └── tools/              # seed, hash_gen, create_test_user, encrypt_oauth_tokens
│   ├── internal/
│   │   ├── api/                # router.go + routes_*.go (28 fichiers)
│   │   ├── core/               # domain services (auth, track, marketplace, ...)
│   │   ├── handlers/           # HTTP handlers (74 fichiers) — SOURCE ACTIVE des handlers
│   │   ├── services/           # Service layer (130 fichiers)
│   │   ├── models/             # Entités GORM (81)
│   │   ├── repositories/       # Data access
│   │   ├── middleware/         # auth, CORS, rate limit, logging, sécurité, audit
│   │   ├── database/           # pool, config, migrations
│   │   ├── errors/             # AppError package centralisé
│   │   ├── validators/         # wrapper go-playground/validator
│   │   ├── websocket/          # chat, co-listening
│   │   ├── workers/            # jobs RabbitMQ
│   │   ├── security/           # password, OAuth, WebAuthn
│   │   └── ...                 # (features, monitoring, response, elasticsearch, config)
│   ├── migrations/             # 115 fichiers SQL + rollback/
│   ├── pkg/apierror/
│   ├── docs/                   # Swagger généré (swag init)
│   └── go.mod                  # Go 1.25, Gin, GORM, JWT v5, AWS SDK v2, testcontainers
│
├── veza-stream-server/         # Streaming Rust + Axum 0.8 + Tokio 1.35
│   ├── src/
│   │   ├── main.rs
│   │   ├── lib.rs
│   │   ├── routes/             # REST endpoints (HLS, encoding, transcode)
│   │   ├── streaming/          # hls.rs, websocket.rs, adaptive.rs, protocols/
│   │   │                       # ⚠️ DASH/WebRTC stubbed (commentés mod.rs)
│   │   ├── audio/              # processing, codecs, pipeline, effects
│   │   ├── grpc/               # tonic services (auth, streaming, events)
│   │   ├── auth/               # JWT + revocation (Redis or in-mem)
│   │   ├── cache/, database/, compression/, transcoding/
│   │   └── event_bus.rs        # RabbitMQ avec fallback degraded mode
│   └── Cargo.toml              # Axum 0.8, Tokio 1.35, Symphonia 0.5, sqlx 0.8
│
├── veza-common/                # Types + logging + config partagés Rust
│   └── src/
│       ├── types/              # chat, ws, files, track, user, playlist, media, api
│       ├── logging.rs          # LoggingConfig utilisé par stream server
│       └── auth.rs, metrics.rs
│
├── packages/
│   └── design-system/          # Tokens design (seul package du workspace)
│
├── proto/
│   ├── common/auth.proto       # AuthService (utilisé gRPC stream↔backend)
│   ├── stream/stream.proto     # StreamService
│   └── chat/chat.proto         # ⚠️ SPEC HISTORIQUE — le chat est en Go
│
├── docs/
│   ├── API_REFERENCE.md        # ⚠️ maintenance manuelle, risque drift
│   ├── ENV_VARIABLES.md        # À maintenir
│   ├── ONBOARDING.md           # Setup dev
│   ├── PROJECT_STATE.md        # État courant
│   ├── FEATURE_STATUS.md       # Features opérationnelles
│   ├── PRODUCTION_DEPLOYMENT.md
│   ├── STAGING_DEPLOYMENT.md
│   ├── SECURITY_SCAN_RC1.md
│   └── archive/                # Retros, smoke tests, plans historiques
│                               # (v0.12.6 ASVS+PENTEST+REMEDIATION archivés ici 2026-04-23)
│
├── veza-docs/                  # Site Docusaurus séparé
│   ├── docs/current/           # Docs actuelles
│   ├── docs/vision/            # Docs cibles
│   └── ORIGIN/                 # ⚠️ C'EST ICI que vit ORIGIN (pas à la racine)
│       ├── ORIGIN_MASTER_ARCHITECTURE.md
│       ├── ORIGIN_CODE_STANDARDS.md
│       ├── ORIGIN_FEATURES_REGISTRY.md
│       ├── ORIGIN_SECURITY_FRAMEWORK.md
│       ├── ORIGIN_UI_UX_SYSTEM.md
│       └── ...
│
├── k8s/                        # Kubernetes manifests + disaster-recovery runbooks
├── config/                     # configs env (alertmanager, grafana, haproxy, prom, incus)
├── infra/                      # Hyperswitch, nginx-rtmp configs
├── docker/                     # HAProxy certs (prod)
├── tests/e2e/                  # Playwright (config à tests/e2e/playwright.config.ts)
├── docker-compose.yml          # Dev avec services dockerisés
├── docker-compose.dev.yml      # Infra only (apps sur l'hôte)
├── docker-compose.prod.yml     # Blue-green + haproxy + alertmanager
├── docker-compose.staging.yml  # Staging avec Caddy
├── docker-compose.test.yml     # CI (tmpfs)
├── Makefile                    # include make/*.mk
├── package.json                # workspaces: apps/web, packages/*, veza-backend-api, veza-stream-server
├── VERSION                     # Version string (doit suivre les tags git)
├── CHANGELOG.md
└── VEZA_VERSIONS_ROADMAP.md    # Historique des versions (v0.9.x → v1.0.x)
```

### Ce qui N'EXISTE PAS — ne pas chercher

- ❌ `backend/` à la racine → c'est `veza-backend-api/`
- ❌ `frontend/` à la racine → c'est `apps/web/`
- ❌ `ORIGIN/` à la racine → c'est `veza-docs/ORIGIN/`
- ❌ `veza-chat-server/` → supprimé au commit `05d02386d` (2026-02-22, v0.502). Le chat est 100% côté Go backend (`internal/handlers/`, `internal/websocket/`). Les `.proto` de chat restent comme spec historique.
- ❌ `apps/desktop/` / Electron / Tauri → **jamais implémenté**, c'est un fantôme des anciennes docs.
- ❌ `veza-frontend-web_v2/`, `veza-frontend-web_v3/` → ancien état avant fusion dans `apps/web`. Reste un fichier `apps/web/src/types/v2-v3-types.ts` à auditer.

### Stack technique exacte

| Composant     | Techno                             | Version pinned                                  |
| ------------- | ---------------------------------- | ----------------------------------------------- |
| Backend API   | Go + Gin + GORM                    | **Go 1.25** (bumped pour golangci-lint v2.11.4) |
| Stream        | Rust + Axum + Tokio                | Axum 0.8, Tokio 1.35                            |
| Frontend      | React + Vite + TS strict           | React 18.2, **Vite 7.1.5**, TS 5.9.3            |
| State front   | Zustand 4.5 + React Query 5.17     |                                                 |
| HTTP client   | Axios 1.13                         |                                                 |
| OpenAPI typegen | **orval ^7** (services + RQ hooks) | `apps/web/orval.config.ts`. Source unique depuis v1.0.8 B9 — `@openapitools/openapi-generator-cli` désinstallé. |
| Postgres      | 16                                 | docker-compose pinned                           |
| Redis         | 7                                  |                                                 |
| Elasticsearch | 8.11.0                             | docker-compose.dev.yml uniquement (orphelin prod, search utilise Postgres FTS) |
| RabbitMQ      | 3-management                       |                                                 |
| ClamAV        | 1.4                                | SEC-MED-003                                     |
| MinIO         | RELEASE.2025-09-07T16-13-09Z       | 4 compose files pinned (commit `4310dbb7`)      |
| Hyperswitch   | 2026.03.11.0                       |                                                 |
| JWT           | RS256 prod / HS256 fallback dev    | jwt v5                                          |
| CI            | Forgejo Actions (self-hosted R720) | `.github/workflows/{ci,e2e,go-fuzz,security-scan,trivy-fs}.yml` |
| E2E           | Playwright 1.57 (`@critical` PR / full push+nightly) | `tests/e2e/playwright.config.ts`, runbook `docs/CI_E2E.md` |

---

## 🚫 Règles immuables — jamais violer

Ces règles sont **absolues**. Si une tâche semble les contredire, la règle gagne.

1. **JAMAIS de code AI/ML** — modules F456-F470 supprimés définitivement. Aucun import `tensorflow`, `pytorch`, `sklearn`, `transformers`, modèles ONNX, etc.
2. **JAMAIS de blockchain/Web3** — modules F491-F500 supprimés. Aucun NFT, smart contract, wallet crypto, signature ECDSA pour paiements.
3. **JAMAIS de gamification** — modules F536-F550 supprimés. Aucun XP, streak, leaderboard, badge, level up, "points", "achievements".
4. **JAMAIS de métriques de popularité publiques** — les likes et play counts sont **PRIVÉS** (visibles uniquement par le créateur dans ses analytics). Aucun compteur visible sur les vues publiques.
5. **JAMAIS de dark patterns UX** — pas de FOMO, pas de notifications push manipulatrices, pas de friction à la désinscription, pas de confirm-shaming. Ref : `veza-docs/ORIGIN/ORIGIN_UI_UX_SYSTEM.md` §13.
6. **JAMAIS modifier les fichiers `veza-docs/ORIGIN/**/\*.md`\*\* — ils sont la spécification de référence, pas du code. Tu implémentes, tu ne modifies pas la spec.
7. **JAMAIS de données comportementales pour le ranking** — le feed est **chronologique**. La découverte est par tags/genres **déclaratifs**. Pas de "tu aimeras aussi" basé sur l'historique.
8. **TOUJOURS propager `context.Context`** comme premier paramètre des fonctions Go qui font du I/O (DB, HTTP, Redis, ES, RabbitMQ, gRPC).
9. **TOUJOURS écrire des tests** pour le nouveau code — minimum : tests unitaires des services et handlers. Intégration si l'infra est touchée.
10. **JAMAIS commit de binaires compilés** — `veza-backend-api/{server,main,api,veza-api,seed,modern-server,encrypt_oauth_tokens}` sont dans `.gitignore`. Si tu crées un binaire pour tests, ne l'ajoute pas à git.
11. **JAMAIS commit de rapports générés** — `coverage*.out`, `lint_report*.json`, `tsc_*.log`, `storybook_*.json` sont ignorés. Ils vivent en local ou dans les artifacts CI, pas en git.
12. **JAMAIS commit de docs de session** — les `RESUME_*.md`, `PLAN_V*.md`, `AUDIT_*.md`, `FIX_*.md`, `PROGRES_*.md`, etc. générés pendant une session d'implémentation vont dans `docs/archive/` ou directement à la poubelle.

---

## 📐 Conventions de code

### Go (backend)

- Framework : **Gin**
- ORM : **GORM**
- Error package centralisé : [`internal/errors`](veza-backend-api/internal/errors) — `AppError{Code, Message, Err, Details, Context}`, utilisé via `RespondWithAppError(c, err)`
- Validation : `go-playground/validator/v10` via [`internal/validators`](veza-backend-api/internal/validators)
- Format réponse d'erreur :
    ```json
    {
        "error": {
            "code": "RESOURCE_NOT_FOUND",
            "message": "Track 123 not found",
            "context": { "track_id": "123" }
        }
    }
    ```
- Format réponse paginée :
    ```json
    {
      "data": [...],
      "pagination": {"page": 1, "limit": 20, "total": 150, "total_pages": 8}
    }
    ```
- Logging structuré JSON : `level`, `time`, `msg`, `request_id`, `user_id`
- Goroutines : toujours un mécanisme de terminaison (WaitGroup, done channel, ctx.Done())
- JWT : **RS256 en prod** (clés RSA), fallback HS256 dev. Access token 5min, refresh 7j. Cookies httpOnly.
- Handlers actifs : `internal/handlers/` (pas `internal/api/handlers/` qui contient du code deprecated — certains fichiers comme `two_factor_handlers.go` y sont marqués DEPRECATED)

### Rust (stream server)

- Edition 2021
- Safety : **0 `unsafe`**. Ne pas introduire de code unsafe sans justification extrême.
- Style : `cargo fmt` + `cargo clippy` (les warnings sont actuellement permissifs, backlog de résorption)
- Tests : `#[cfg(test)]` colocalisés
- Pas de `opus`, `webrtc`, `lame`, `fdkaac` (deps natives manquantes — Symphonia couvre les besoins)

### TypeScript (frontend)

- **TS strict** + `noUncheckedIndexedAccess: true`
- ARIA labels sur tous les composants interactifs
- Keyboard nav (Tab, Enter, Escape)
- Lazy loading des routes (`React.lazy` + `Suspense`) — registry dans [`src/components/ui/LazyComponent.tsx`](apps/web/src/components/ui/LazyComponent.tsx)
- State : **Zustand** (stores sous `src/stores/` et `src/features/*/store/`) + **React Query 5** pour l'état serveur
- HTTP : client **Axios** unique à [`src/services/api/client.ts`](apps/web/src/services/api/client.ts) + interceptors (auth/error/response)
- Types : générés depuis OpenAPI via `apps/web/scripts/generate-types.sh` (pre-commit hook)
- i18n : `react-i18next` 15
- Pas de `moment` (déprécié — utiliser `date-fns@4`)

### API REST

```go
// Conventions de routes
router.GET("/api/v1/{resource}",       handler.List)      // ?page=1&limit=20
router.GET("/api/v1/{resource}/:id",   handler.Get)
router.POST("/api/v1/{resource}",      handler.Create)
router.PUT("/api/v1/{resource}/:id",   handler.Update)
router.DELETE("/api/v1/{resource}/:id", handler.Delete)
```

---

## 💡 Commandes utiles

```bash
# --- Développement ---
make dev                    # Backend docker + web local (mode principal)
make dev-full               # Tout local avec hot reload
make dev-backend-api        # Backend Go seul
make dev-stream-server      # Rust stream server seul
make dev-web                # Frontend Vite seul
make doctor                 # Vérifie les dépendances système

# --- Infra seule ---
make infra-up-dev           # Postgres, Redis, RabbitMQ, ES, MinIO, ClamAV
make infra-down             # Stop infra

# --- Tests ---
make test                   # Tous les tests
make test-backend-api       # Go unit tests
make test-web               # Vitest frontend
make test-stream-server     # Cargo test
make lint                   # Linting complet (golangci-lint, ESLint, clippy)

# --- Backend Go spécifique ---
cd veza-backend-api
go test ./internal/... -short -count=1
go test ./internal/... -short -count=1 -v -run TestXxx
VEZA_SKIP_INTEGRATION=1 go test ./internal/... -count=1   # skip testcontainers
go build ./...
gofmt -l -w .

# --- Rust stream server ---
cd veza-stream-server
cargo fmt
cargo clippy
cargo test

# --- Frontend ---
cd apps/web
npm run dev
npm run build
npm test -- --run
npm run lint

# --- Base de données ---
make migrate-up
make migrate-down
make migrate-create NAME=add_xxx_column

# --- E2E ---
npm run e2e:critical       # Playwright tests tagués @critical
npm run e2e                # Tous les E2E
```

### Bypass des hooks (à utiliser avec discernement)

Le pre-commit hook (`.husky/pre-commit`) peut être bypassé par **variables d'env documentées dans le hook** :

- `SKIP_TYPES=1` — skip la régénération des types depuis OpenAPI
- `SKIP_TESTS=1` — skip vitest sur les fichiers changés

Le pre-push hook (`.husky/pre-push`) :

- `SKIP_E2E=1` — skip les Playwright `@critical` (utile si l'infra Docker n'est pas up)

**Ne jamais utiliser `--no-verify`** sauf cas exceptionnel clairement documenté dans le message de commit (ex : commit de pure suppressions de fichiers où lint-staged corrompt l'index).

---

## 📝 Convention de commits

Conventional Commits + scope :

```
feat(backend): add playlist sharing by token
fix(web): resolve feed rendering bug on iOS Safari
refactor(stream): extract HLS manifest generator
test(backend): add integration tests for 2FA flow
docs: update ENV_VARIABLES.md
chore(cleanup): archive session docs from apps/web
ci: bump Go to 1.25 to match golangci-lint v2
```

Scopes usuels : `backend`, `web`, `stream`, `common`, `infra`, `ci`, `docs`, `deps`, `cleanup`, `release`.

Format du message :

```
<type>(<scope>): <sujet court impératif, minuscule, ≤70 chars>

<corps optionnel: explique pourquoi, pas quoi>

<footer optionnel: Co-Authored-By, Refs, Closes>
```

Co-author requis quand l'agent contribue :

```
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```

---

## 🎯 Scope du projet — ce qu'on fait, ce qu'on refuse

Veza est une **plateforme de streaming musical éthique** pour créateurs et auditeurs. Les axes :

**On fait** :

- Upload, stockage, streaming (HLS) de tracks
- Library, playlists, partage par token
- Feed chronologique, découverte par genres/tags **déclaratifs**
- Chat et co-listening (WebSocket)
- Livestream RTMP + HLS
- Marketplace créateur (gear, services, sessions)
- Analytics créateur (privés)
- Abonnements (Hyperswitch)
- Distribution vers plateformes externes
- Education / formation
- PWA, i18n

**On refuse** :

- Toute forme d'IA recommandation comportementale (cf. règle 7)
- Popularité publique (cf. règle 4)
- Gamification (cf. règle 3)
- Dark patterns (cf. règle 5)
- NFT / Web3 (cf. règle 2)

---

## 🧠 Patterns de résolution

### Quand tu ne sais pas quoi faire

1. Lis `docs/PROJECT_STATE.md` et `docs/FEATURE_STATUS.md` pour l'état courant.
2. Si spec : lis `veza-docs/ORIGIN/` (lecture seule).
3. Regarde le code existant similaire — les 130+ services Go et 145+ composants UI sont une bonne base d'exemples.
4. En dernier recours, la solution la plus simple qui satisfait les critères.

### Quand un test échoue

1. Lis l'erreur complète.
2. Vérifie que les migrations DB sont appliquées (`make migrate-up`).
3. Vérifie que l'infra tourne (`make infra-up-dev`).
4. Reproduire localement, pas deviner.
5. Fix soit le test soit le code — pas les deux en même temps.

### Quand tu trouves un bug existant

1. Fix-le si dans le scope de ta tâche actuelle.
2. Sinon `// TODO(<scope>): description` et note dans le PR description.
3. Ne jamais casser un test qui passait pour en faire passer un nouveau.

### Quand une dépendance manque

```bash
# Go
cd veza-backend-api && go get <module>@<version>

# Frontend
cd apps/web && npm install <package>

# Rust
cd veza-stream-server && cargo add <crate>
```

Licence acceptable : MIT, Apache-2.0, BSD-2/3, ISC, MPL-2.0. **GPL interdit** dans le backend.

### Quand tu dois modifier un fichier modifié en parallèle

Le repo a des commits parallèles (mainteneur + bots Forgejo). Si `git pull` donne un conflit :

1. Ne jamais force-push sur `main`.
2. Résoudre proprement, commit de résolution explicite.
3. Si doute, demander.

---

## 🚨 Actions qui nécessitent une confirmation humaine

**NE JAMAIS faire sans demander** :

- `git push --force` ou `git push --force-with-lease` sur `main`
- `git reset --hard` qui perd du travail
- `git filter-repo` / purge d'historique
- Supprimer des branches distantes (`git push --delete`)
- Supprimer des tags distants
- Modifier `.github/workflows/*.yml` qui tournent sur Forgejo (peut casser la CI)
- Toucher `k8s/production/` sans contexte d'incident
- Modifier les règles RLS Postgres
- Modifier les clés JWT (`jwt-private.pem`, `jwt-public.pem`)
- Modifier les secrets (`docker-compose.prod.yml` env, `.env.production`)

**Peut faire sans demander** :

- Tout commit local + push simple (`git push origin main`) si la branche ne diverge pas
- Éditer les fichiers `.md` de documentation
- Éditer le code applicatif (Go, Rust, TS) avec tests
- Ajouter des migrations SQL
- Modifier `docker-compose.dev.yml` et configs de dev

---

## 📜 Historique

- **2026-04-14** : Réécriture complète post-audit (v1.0.4). L'ancienne version référençait `backend/`, `frontend/`, `ORIGIN/` à la racine, un chat server Rust et un desktop Electron qui n'existaient pas ou plus. Voir `AUDIT_REPORT.md` pour le détail.
- **2026-02-22** (commit `05d02386d`) : suppression de `veza-chat-server/` (chat intégré au backend Go depuis v0.502).
- **2026-03-03** : release `v1.0.0`.
- **2026-03-13** : tag `v1.0.2`.
- **2026-04-14** : tag `v1.0.3` existant, cible `v1.0.4` pour la release post-cleanup.
- **2026-04-23** : release `v1.0.7` (BFG history rewrite, .git 2.3 GB → 66 MB, transactions marketplace, UserRateLimiter wired).
- **2026-04-26** : release `v1.0.8` (MinIO storage end-to-end, OpenAPI orval migration, drop `@openapitools/openapi-generator-cli` legacy generator, E2E Playwright workflow + `--ci` seed flag, queue+password handler annotations, full authService → orval).

---

_Source de vérité pour le comportement de Claude Code sur Veza. Ne jamais modifier sans commit explicite (`docs: update CLAUDE.md [raison]`)._