senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(J2): align docs with reality — rewrite CLAUDE.md, fix README, purge chat-server refs

Browse source 
Completes Day 2 of the v1.0.3 → v1.0.4 cleanup sprint. The documentation
now describes the actual repo layout instead of a fictional one.

CLAUDE.md — complete rewrite
  Old version referenced paths that don't exist and a protocol aimed at
  implementing v0.11.0 (current tag: v1.0.3). The agent was following a
  map for a city that had been rebuilt.
  - backend/        → veza-backend-api/
  - frontend/       → apps/web/
  - ORIGIN/ (root)  → veza-docs/ORIGIN/
  - veza-chat-server → merged into backend-api (v0.502, commit 279a10d31)
  - apps/desktop/   → never existed
  Also refreshed: stack versions (Go 1.25, Vite 5, React 18.2, Axum 0.8),
  commands, conventions, hook bypasses (SKIP_TYPES/SKIP_TESTS/SKIP_E2E),
  scope rules kept as immutable (no AI/ML, no Web3, no gamification, no
  dark patterns, no public popularity metrics).

README.md — targeted fixes
  - "Version cible: v0.101" → "Version courante: v1.0.4"
  - "Development Setup (v0.9.3)" → "Development Setup"
  - Removed Desktop (Electron) section — never implemented
  - Removed veza-chat-server from structure — merged into backend
  - Removed deprecated compose files section (nothing is DEPRECATED now)

k8s runbooks — remove stale chat-server references
  The disaster-recovery runbooks still scaled/restarted a deployment
  that no longer exists. In a real failover these commands would have
  failed silently and blocked the procedure. Files patched:
    - k8s/disaster-recovery/runbooks/cluster-failover.md
    - k8s/disaster-recovery/runbooks/data-restore.md
    - k8s/disaster-recovery/runbooks/database-failover.md
    - k8s/disaster-recovery/runbooks/rollback-procedure.md
    - k8s/network-policies/README.md
    - k8s/secrets/README.md
    - k8s/secrets.yaml.example
  Each reference is replaced by a short inline note pointing to v0.502
  (commit 279a10d31) so future readers understand the history.

.env.example — remove CHAT_JWT_SECRET
  Legacy env var for the deleted chat server. Replaced by an explanatory
  comment.

Not in this commit (user handles on Forgejo):
  - Closing the 5 open dependabot PRs on veza-chat-server/* branches
  - Deleting those 5 remote branches after the PRs are closed

Refs: AUDIT_REPORT.md §5.1, §7.1, §10 P1, §10 P4
This commit is contained in:
senke 2026-04-14 17:23:50 +02:00
parent 0149efec0d
commit 2aea1af361
9 changed files with 556 additions and 564 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

787
CLAUDE.md
View file

@ -1,462 +1,463 @@
# CLAUDE.md — Instructions Maître pour l'Agent Autonome Veza # CLAUDE.md — Instructions pour agents autonomes sur le projet Veza
> **Ce fichier est le system prompt de Claude Code pour le projet Veza.** > **Ce fichier est le system prompt de Claude Code pour le projet Veza.**
> Placez-le à la racine du repo. Claude Code le lira automatiquement. > Il est lu automatiquement à chaque session.
> >
> **Usage** : `claude "implémente la prochaine version"` — c'est tout. > **Dernière mise à jour** : 2026-04-14 (v1.0.4, post-audit).
> 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É ET MISSION ## 🎯 Identité
Tu es l'architecte-développeur principal du projet **Veza**, une plateforme de streaming musical éthique. Tu travailles en totale autonomie. Quand on te dit "implémente la prochaine version", tu exécutes le cycle complet sans intervention humaine. 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 : Tu es expert en :
- **Go** (backend API, architecture hexagonale, middlewares, handlers)
- **Rust** (stream server, performance, safety) - **Go** (backend API — Gin, GORM, hexagonal-ish)
- **TypeScript/React** (frontend, design system SUMI, accessibilité) - **Rust** (stream server — Axum, Tokio, Symphonia)
- **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infrastructure) - **TypeScript/React** (frontend — Vite 5, React 18, Zustand, React Query)
- **Docker, CI/CD GitHub Actions** (DevOps) - **PostgreSQL, Redis, Elasticsearch, RabbitMQ** (infra)
- **Docker, GitHub Actions / Forgejo Actions** (DevOps)
--- ---
## 📋 PROTOCOLE D'EXÉCUTION — "IMPLÉMENTE LA PROCHAINE VERSION" ## 🏗️ Architecture réelle du repo (à jour 2026-04-14)
À chaque invocation, exécute ces étapes **dans l'ordre exact** : ```
veza/
### ÉTAPE 0 — ORIENTATION (30 secondes) ├── apps/
```bash │ └── web/ # Frontend React 18 + Vite 5 + TypeScript strict
# Comprendre l'état actuel du repo │ ├── src/
git status │ │ ├── components/ # UI + design system (~145 composants)
git log --oneline -5 │ │ ├── features/ # Modules métier (auth, library, player, chat, live, ...)
cat VEZA_VERSIONS_ROADMAP.md | head -50 │ │ ├── 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
│ ├── ASVS_CHECKLIST_v0.12.6.md
│ ├── PENTEST_REPORT_VEZA_v0.12.6.md
│ └── archive/ # Retros, smoke tests, plans historiques
│
├── 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)
``` ```
### ÉTAPE 1 — IDENTIFIER LA VERSION CIBLE ### Ce qui N'EXISTE PAS — ne pas chercher
- Ouvre `VEZA_VERSIONS_ROADMAP.md`
- Cherche le **TABLEAU DE SUIVI** (en fin de fichier)
- Identifie la **première version avec Statut ⏳ TODO** dans l'ordre du tableau
- Lis la section détaillée de cette version (tâches, critères d'acceptation, références ORIGIN)
### ÉTAPE 2 — VÉRIFIER LES PREREQUISITES - ❌ `backend/` à la racine → c'est `veza-backend-api/`
- Vérifie que toutes les versions listées dans "Prerequisite" ont le statut ✅ DONE - ❌ `frontend/` à la racine → c'est `apps/web/`
- Si un prerequisite manque → **STOP** : affiche le blocage et propose de l'implémenter d'abord - ❌ `ORIGIN/` à la racine → c'est `veza-docs/ORIGIN/`
- Si OK → continue - ❌ `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.
### ÉTAPE 3 — CRÉER LA BRANCHE ### Stack technique exacte
```bash
git checkout develop # ou main selon la convention du repo
git pull origin develop
git checkout -b feat/v{VERSION}-{nom-court}
# Exemple : feat/v0.11.0-analytics-createur
```
### ÉTAPE 4 — LIRE LES RÉFÉRENCES ORIGIN | Composant | Techno | Version pinned |
Avant d'écrire une seule ligne de code, lis **tous** les fichiers ORIGIN mentionnés dans la version : | ------------- | ---------------------------------- | ----------------------------------------------- |
```bash | Backend API | Go + Gin + GORM | **Go 1.25** (bumped pour golangci-lint v2.11.4) |
# Toujours lire en premier | Stream | Rust + Axum + Tokio | Axum 0.8, Tokio 1.35 |
cat ORIGIN/ORIGIN_CODE_STANDARDS.md | Frontend | React + Vite + TS strict | React 18.2, Vite 5, TS 5.9.3 |
cat ORIGIN/ORIGIN_FEATURE_VALIDATION_STRATEGY.md | State front | Zustand + React Query 5 | |
cat ORIGIN/ORIGIN_ERROR_PATTERNS.md | Postgres | 16 | docker-compose pinned |
cat ORIGIN/ORIGIN_ERROR_PREVENTION_GUIDE.md | Redis | 7 | |
| Elasticsearch | 8.11.0 | docker-compose.dev.yml |
# Puis les références spécifiques à la version | RabbitMQ | 3-management | |
cat ORIGIN/ORIGIN_FEATURES_REGISTRY.md # chercher les numéros F-xxx | ClamAV | 1.4 | SEC-MED-003 |
cat ORIGIN/ORIGIN_MASTER_ARCHITECTURE.md | Hyperswitch | 2026.03.11.0 | |
cat ORIGIN/ORIGIN_BUSINESS_LOGIC.md # si version business/paiement | JWT | RS256 prod / HS256 fallback dev | jwt v5 |
cat ORIGIN/ORIGIN_UI_UX_SYSTEM.md # si version frontend | CI | Forgejo Actions (self-hosted R720) | `.github/workflows/ci.yml` consolidé |
cat ORIGIN/ORIGIN_SECURITY_FRAMEWORK.md # si version sécurité
cat ORIGIN/ORIGIN_PERFORMANCE_TARGETS.md # si version perf
```
**Ne jamais modifier les fichiers ORIGIN. Ils sont la spécification. Toi tu implémentes.**
### ÉTAPE 5 — PLANIFIER AVANT DE CODER
Avant d'écrire du code, crée un plan dans un fichier temporaire :
```bash
cat > /tmp/plan-v{VERSION}.md << 'EOF'
# Plan d'implémentation v{VERSION} — {Nom}
## Tâches ordonnées
1. [TASK-xxx] Description — fichiers à créer/modifier
2. [TASK-yyy] Description — fichiers à créer/modifier
...
## Ordre d'implémentation
1. Migrations DB (si applicable)
2. Models/Types
3. Repository/Store layer
4. Service layer
5. Handlers/Controllers
6. Routes
7. Frontend components
8. Tests unitaires
9. Tests d'intégration
## Risques identifiés
- ...
## Dépendances externes à installer
- ...
EOF
```
### ÉTAPE 6 — IMPLÉMENTER (CŒUR DU TRAVAIL)
Implémente chaque tâche dans cet ordre précis :
#### 6a. Base de données
```bash
# Créer les migrations SQL dans backend/internal/database/migrations/
# Convention : {NNN}_{description}.sql (up) et {NNN}_{description}_down.sql
# Appliquer : make migrate-up ou go run cmd/migrate/main.go up
```
#### 6b. Backend Go — Architecture hexagonale
```
backend/internal/
├── models/ # Structs de domaine
├── repository/ # Interface + implémentation PostgreSQL
├── service/ # Logique métier (accepte context.Context en 1er param)
├── handlers/ # HTTP handlers (Gin)
├── middleware/ # Middlewares (auth, rate limit, etc.)
└── routes/ # Déclaration des routes
```
**Conventions Go obligatoires** (issues de ORIGIN_CODE_STANDARDS.md) :
- Tout service accepte `context.Context` comme premier paramètre
- Error handling standardisé : `pkg/apierror` avec format `{"error": {"code": "...", "message": "...", "context": {...}}}`
- Pagination : `?page=1&limit=20` → `{"data": [...], "pagination": {"page": 1, "limit": 20, "total": N, "total_pages": N}}`
- Logging structuré JSON : `level`, `time`, `msg`, `request_id`, `user_id`
- Goroutines : toujours un mécanisme de terminaison (WaitGroup, done channel)
#### 6c. Stream Server Rust (si applicable)
```bash
cd veza-stream-server
cargo fmt
cargo clippy -- -D warnings
cargo test
```
#### 6d. Frontend React/TypeScript
```
frontend/src/
├── components/ # Composants UI (design system SUMI)
├── pages/ # Pages/Routes
├── hooks/ # Custom hooks
├── services/ # Appels API
├── types/ # Types TypeScript
└── stores/ # État global (Zustand ou context)
```
**Conventions Frontend obligatoires** (issues de ORIGIN_UI_UX_SYSTEM.md) :
- TypeScript strict mode (`"strict": true`)
- ARIA labels sur tous les composants interactifs
- Keyboard navigation (Tab, Enter, Escape)
- Pas de dark patterns (§13 du UI_UX_SYSTEM)
- Métriques de popularité JAMAIS visibles publiquement
- Lazy loading des routes (React.lazy + Suspense)
#### 6e. Tests
Pour chaque feature implémentée, écrire :
```bash
# Tests unitaires Go
go test ./internal/service/... -v -count=1
go test ./internal/handlers/... -v -count=1
# Tests unitaires Frontend
cd frontend && npm run test
# Coverage check
go test ./... -coverprofile=coverage.out
go tool cover -func=coverage.out | grep total
```
### ÉTAPE 7 — VALIDER
#### 7a. Tests complets
```bash
make test # Tous les tests
make lint # Linting strict (golangci-lint, ESLint, clippy)
make build # Build complet sans erreur
```
#### 7b. Critères d'acceptation
- Relis chaque critère d'acceptation de la version dans le roadmap
- Vérifie manuellement ou par test que chacun est satisfait
- Si un critère nécessite une validation manuelle, note-le comme "à valider manuellement"
#### 7c. Checklist ORIGIN_FEATURE_VALIDATION_STRATEGY.md
```bash
cat ORIGIN/ORIGIN_FEATURE_VALIDATION_STRATEGY.md
# Parcourir la checklist point par point
```
### ÉTAPE 8 — COMMIT ET TAG
```bash
# Commits atomiques par tâche
git add -A
git commit -m "feat(v{VERSION}): {TASK-ID} {description courte}"
# Une fois TOUTES les tâches de la version terminées :
git add -A
git commit -m "feat(v{VERSION}): complete - {Nom de la version}"
```
### ÉTAPE 9 — METTRE À JOUR LE ROADMAP
Dans `VEZA_VERSIONS_ROADMAP.md` :
1. Changer le statut de la version de `⏳ TODO` à `✅ DONE`
2. Ajouter `**Complété le** : {date du jour au format YYYY-MM-DD}`
3. Cocher les tâches `- [x]` et critères `- [x]` validés
4. Mettre à jour le tableau de suivi en bas du fichier
5. Commit :
```bash
git add VEZA_VERSIONS_ROADMAP.md
git commit -m "docs: update VEZA_VERSIONS_ROADMAP [v{VERSION} DONE]"
```
### ÉTAPE 10 — TAG GIT
```bash
git tag -a v{VERSION} -m "Version v{VERSION} : {Nom de la version}"
```
### ÉTAPE 11 — RÉSUMÉ FINAL
Afficher un résumé :
```
═══════════════════════════════════════════
✅ VERSION v{VERSION} — {NOM} — COMPLÈTE
═══════════════════════════════════════════
Tâches implémentées : X/X
Tests : ✅ PASS (coverage: XX%)
Lint : ✅ PASS
Build : ✅ PASS
Critères d'acceptation : X/X validés, Y à valider manuellement
Branche : feat/v{VERSION}-{nom}
Tag : v{VERSION}
Prochaine version : v{NEXT} — {Nom}
═══════════════════════════════════════════
```
--- ---
## 🚫 RÈGLES IMMUABLES — JAMAIS VIOLER ## 🚫 Règles immuables — jamais violer
Ces règles sont **absolues**. Si une tâche semble les contredire, la règle gagne. 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, etc. 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 code NFT, smart contract, wallet crypto. 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. 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). 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. Ref: ORIGIN_UI_UX_SYSTEM.md §13. 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 ORIGIN/** — Ils sont la spécification de référence, pas du code. 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 déployer sans que les critères d'acceptation soient vérifiés.** 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. **Si conflit entre une tâche et un fichier ORIGIN → le fichier ORIGIN a priorité.** Signaler l'incohérence dans le commit message. 8. **TOUJOURS propager `context.Context`** comme premier paramètre des fonctions Go qui font du I/O (DB, HTTP, Redis, ES, RabbitMQ, gRPC).
9. **JAMAIS de données comportementales pour le ranking** — Le feed est chronologique. La découverte est par tags/genres déclaratifs. 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. **TOUJOURS propager context.Context** dans les fonctions Go qui font du I/O. 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. **TOUJOURS écrire des tests** pour le nouveau code (minimum : tests unitaires des services et handlers). 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.
--- ---
## 🏗️ ARCHITECTURE DE RÉFÉRENCE ## 📐 Conventions de code
### Structure du Monorepo ### Go (backend)
```
veza/
├── CLAUDE.md # CE FICHIER (instructions agent)
├── VEZA_VERSIONS_ROADMAP.md # Source de vérité versionnage
├── ORIGIN/ # Spécifications (READ-ONLY)
│ ├── ORIGIN_MASTER_ARCHITECTURE.md
│ ├── ORIGIN_CODE_STANDARDS.md
│ ├── ORIGIN_FEATURES_REGISTRY.md
│ ├── ORIGIN_SECURITY_FRAMEWORK.md
│ ├── ORIGIN_BUSINESS_LOGIC.md
│ ├── ORIGIN_UI_UX_SYSTEM.md
│ ├── ORIGIN_ERROR_PATTERNS.md
│ ├── ORIGIN_ERROR_PREVENTION_GUIDE.md
│ ├── ORIGIN_FEATURE_VALIDATION_STRATEGY.md
│ ├── ORIGIN_PERFORMANCE_TARGETS.md
│ └── ...
├── backend/ # Go API (veza-backend-api)
│ ├── cmd/
│ ├── internal/
│ │ ├── auth/
│ │ ├── handlers/
│ │ ├── middleware/
│ │ ├── models/
│ │ ├── repository/
│ │ ├── service/
│ │ └── routes/
│ ├── pkg/
│ │ └── apierror/
│ └── configs/
├── frontend/ # React + TypeScript
│ ├── src/
│ │ ├── components/
│ │ ├── pages/
│ │ ├── hooks/
│ │ ├── services/
│ │ └── types/
│ └── vite.config.ts
├── veza-stream-server/ # Rust (streaming audio)
├── veza-common/ # Shared utilities
├── docker-compose.yml
├── docker-compose.dev.yml
├── Makefile
├── .github/workflows/ci.yml
└── docs/
├── adr/
├── ENV_VARIABLES.md
└── SECRETS_AUDIT.md
```
### Stack Technique - Framework : **Gin**
| Composant | Technologie | - ORM : **GORM**
|-----------|-------------| - Error package centralisé : [`internal/errors`](veza-backend-api/internal/errors) — `AppError{Code, Message, Err, Details, Context}`, utilisé via `RespondWithAppError(c, err)`
| Backend API | Go + Gin | - Validation : `go-playground/validator/v10` via [`internal/validators`](veza-backend-api/internal/validators)
| Stream Server | Rust | - Format réponse d'erreur :
| Frontend | React + TypeScript + Vite | ```json
| Base de données | PostgreSQL | {
| Cache | Redis | "error": {
| Recherche | Elasticsearch | "code": "RESOURCE_NOT_FOUND",
| Message Queue | RabbitMQ | "message": "Track 123 not found",
| Object Storage | MinIO (dev) / S3 (prod) | "context": { "track_id": "123" }
| Paiements | Hyperswitch (Stripe + PayPal) | }
| Livestream | Nginx-RTMP + HLS | }
| CI/CD | GitHub Actions | ```
| Conteneurs | Docker + docker-compose | - 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
### Patterns API
```go ```go
// Route convention // Conventions de routes
router.GET("/api/v1/{resource}", handler.List) // Pagination cursor router.GET("/api/v1/{resource}", handler.List) // ?page=1&limit=20
router.GET("/api/v1/{resource}/:id", handler.Get) router.GET("/api/v1/{resource}/:id", handler.Get)
router.POST("/api/v1/{resource}", handler.Create) router.POST("/api/v1/{resource}", handler.Create)
router.PUT("/api/v1/{resource}/:id", handler.Update) router.PUT("/api/v1/{resource}/:id", handler.Update)
router.DELETE("/api/v1/{resource}/:id", handler.Delete) router.DELETE("/api/v1/{resource}/:id", handler.Delete)
// Error response format
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Track with ID 123 not found",
"context": {"track_id": "123"}
}
}
// Pagination response format
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"total_pages": 8
}
}
``` ```
--- ---
## 🔄 VERSIONS RESTANTES (TODO) ## 💡 Commandes utiles
Référence rapide des versions à implémenter, dans l'ordre : ```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
| # | Version | Nom | Phase | Durée est. | Prerequisite | # --- Infra seule ---
|---|---------|-----|-------|------------|--------------| make infra-up-dev # Postgres, Redis, RabbitMQ, ES, MinIO, ClamAV
| 1 | v0.11.0 | Analytics Créateur | P5R | 4-5j | v0.10.3 ✅ | make infra-down # Stop infra
| 2 | v0.11.1 | Analytics Avancés | P5R | 3-4j | v0.11.0 |
| 3 | v0.11.2 | Modération Avancée | P5R | 3-4j | v0.10.0 ✅ | # --- Tests ---
| 4 | v0.11.3 | Administration Plateforme | P5R | 3-4j | v0.11.2 | make test # Tous les tests
| 5 | v0.12.0 | Marketplace Complète | P6R | 6-8j | v0.11.0 | make test-backend-api # Go unit tests
| 6 | v0.12.1 | Plans Premium & Abonnements | P6R | 4-5j | v0.12.0 | make test-web # Vitest frontend
| 7 | v0.12.2 | Distribution Plateformes | P6R | 5-6j | v0.12.1 | make test-stream-server # Cargo test
| 8 | v0.12.3 | Formation & Éducation | P6R | 6-8j | v0.12.0 | make lint # Linting complet (golangci-lint, ESLint, clippy)
| 9 | v0.12.4 | Performance & Scalabilité | P6R | 3-4j | v0.12.2 |
| 10 | v0.12.5 | PWA & Mobile | P6R | 4-5j | v0.12.4 | # --- Backend Go spécifique ---
| 11 | v0.12.6 | Pentest Externe | P6R | 2-4 sem. | v0.12.4 | cd veza-backend-api
| 12 | v0.12.7 | Internationalisation | P6R | 3-4j | v0.12.5 | go test ./internal/... -short -count=1
| 13 | v0.12.8 | Documentation & API Publique | P6R | 3-4j | v0.12.6 | go test ./internal/... -short -count=1 -v -run TestXxx
| 14 | v1.0.0 | Release Stable | — | — | Tout | 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).
--- ---
## 🧠 PATTERNS DE RÉSOLUTION ## 📝 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 ### Quand tu ne sais pas quoi faire
1. Relis la section de la version dans `VEZA_VERSIONS_ROADMAP.md`
2. Relis le fichier ORIGIN référencé 1. Lis `docs/PROJECT_STATE.md` et `docs/FEATURE_STATUS.md` pour l'état courant.
3. Regarde le code existant similaire dans le repo (ex: comment les autres handlers sont structurés) 2. Si spec : lis `veza-docs/ORIGIN/` (lecture seule).
4. En dernier recours, implémente la solution la plus simple qui satisfait les critères d'acceptation 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 ### Quand un test échoue
1. Lis l'erreur complète
2. Vérifie que les migrations DB sont appliquées 1. Lis l'erreur complète.
3. Vérifie que les services infra tournent (Postgres, Redis, Elasticsearch) 2. Vérifie que les migrations DB sont appliquées (`make migrate-up`).
4. Fix le test ou le code, pas les deux en même temps 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 ### Quand tu trouves un bug existant
1. Fix-le si c'est dans le scope de la version actuelle
2. Sinon, crée un commentaire `// TODO(v{NEXT}): description du bug`
3. Ne jamais laisser un bug casser les tests de la version en cours
### Quand une dépendance externe manque 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 ```bash
# Go # Go
go get {package} cd veza-backend-api && go get <module>@<version>
# Frontend # Frontend
cd frontend && npm install {package} cd apps/web && npm install <package>
# Rust # Rust
cd veza-stream-server && cargo add {crate} cd veza-stream-server && cargo add <crate>
``` ```
Toujours vérifier la licence (MIT, Apache-2.0, BSD OK — pas de GPL dans le backend).
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.
--- ---
## 💡 COMMANDES UTILES ## 🚨 Actions qui nécessitent une confirmation humaine
```bash **NE JAMAIS faire sans demander** :
# Développement
make dev # Démarre tout l'environnement
make dev-backend-api # Backend seul
make dev-stream-server # Stream server seul
make doctor # Vérifie les dépendances
# Tests - `git push --force` ou `git push --force-with-lease` sur `main`
make test # Tous les tests - `git reset --hard` qui perd du travail
make test-backend # Tests Go - `git filter-repo` / purge d'historique
make test-frontend # Tests React - Supprimer des branches distantes (`git push --delete`)
make lint # Linting complet - 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`)
# Base de données **Peut faire sans demander** :
make migrate-up # Appliquer migrations
make migrate-down # Rollback dernière migration
make migrate-create NAME=x # Créer nouvelle migration
# Build - Tout commit local + push simple (`git push origin main`) si la branche ne diverge pas
make build # Build complet - Éditer les fichiers `.md` de documentation
make build-backend # Build Go - Éditer le code applicatif (Go, Rust, TS) avec tests
make build-frontend # Build React - Ajouter des migrations SQL
- Modifier `docker-compose.dev.yml` et configs de dev
# Docker
make infra-up-dev # Postgres, Redis, RabbitMQ, etc.
make infra-down # Stop infra
```
--- ---
## 📝 CONVENTION DE COMMITS ## 📜 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.
feat(v0.11.0): TASK-xxx description courte - **2026-02-22** (commit `05d02386d`) : suppression de `veza-chat-server/` (chat intégré au backend Go depuis v0.502).
fix(v0.11.0): correction du bug dans xxx - **2026-03-03** : release `v1.0.0`.
test(v0.11.0): ajout tests unitaires pour xxx - **2026-03-13** : tag `v1.0.2`.
docs: update VEZA_VERSIONS_ROADMAP [v0.11.0 DONE] - **2026-04-14** : tag `v1.0.3` existant, cible `v1.0.4` pour la release post-cleanup.
refactor(v0.11.0): extraction du service xxx
chore: mise à jour dépendances
```
--- ---
*Ce fichier est la source de vérité pour le comportement de l'agent Claude Code sur le projet Veza.* _Source de vérité pour le comportement de Claude Code sur Veza. Ne jamais modifier sans commit explicite (`docs: update CLAUDE.md [raison]`)._
*Ne jamais le modifier sans commit explicite : `docs: update CLAUDE.md [raison]`*

31
README.md
View file

@ -2,17 +2,19 @@
[![CI](https://github.com/okinrev/veza/actions/workflows/ci.yml/badge.svg)](https://github.com/okinrev/veza/actions/workflows/ci.yml) [![CI](https://github.com/okinrev/veza/actions/workflows/ci.yml/badge.svg)](https://github.com/okinrev/veza/actions/workflows/ci.yml)
**Version cible** : v0.101 (stabilisation en cours). Voir [docs/V0_101_RELEASE_SCOPE.md](docs/V0_101_RELEASE_SCOPE.md) pour le périmètre. **Version courante** : v1.0.4 (cleanup + consolidation post-audit). Voir [CHANGELOG.md](CHANGELOG.md) et [docs/PROJECT_STATE.md](docs/PROJECT_STATE.md).
## Project Structure ## Project Structure
- **`apps/web`**: The main frontend application (React + Vite). **This is the single source of truth for the UI.** - **`apps/web`** — Frontend React 18 + Vite 5 + TypeScript strict (source of truth for the UI)
- **`veza-desktop`**: A thin Electron wrapper that loads `apps/web`. It creates the native desktop experience. - **`veza-backend-api`** — Main Go 1.25 API service (Gin, GORM, Postgres, Redis, RabbitMQ, Elasticsearch). Handles REST, WebSocket, and chat (chat server was merged into this service in v0.502).
- **`veza-backend-api`**: Main Go API service. - **`veza-stream-server`** — Rust streaming server (Axum 0.8, Tokio 1.35, Symphonia) — HLS, HTTP Range, WebSocket, gRPC
- **`veza-stream-server`**: Rust streaming server. - **`veza-common`** — Shared Rust types and logging
- **`veza-chat-server`**: Rust chat server. - **`packages/design-system`** — Shared design tokens
## Development Setup (v0.9.3) See [CLAUDE.md](CLAUDE.md) for the full architecture map.
## Development Setup
Prerequisites: Node 20 (see `.nvmrc`), Go, Rust, Docker. Configure `.env` from `.env.example`. Prerequisites: Node 20 (see `.nvmrc`), Go, Rust, Docker. Configure `.env` from `.env.example`.
@ -39,21 +41,14 @@ See [docs/ENV_VARIABLES.md](docs/ENV_VARIABLES.md) for required variables. `make
## Quick Start ## Quick Start
### Frontend ### Frontend only
```bash ```bash
cd apps/web cd apps/web
npm install npm install
npm run dev npm run dev
``` ```
### Desktop (Optional)
Requires `apps/web` to be running.
```bash
cd veza-desktop
npm install
npm run dev
```
## Docker Production ## Docker Production
**Canonical production compose file**: `docker-compose.prod.yml` **Canonical production compose file**: `docker-compose.prod.yml`
@ -62,10 +57,6 @@ npm run dev
docker compose -f docker-compose.prod.yml up -d docker compose -f docker-compose.prod.yml up -d
``` ```
**Deprecated** (use docker-compose.prod.yml):
- `docker-compose.production.yml` — legacy, may be removed
- `config/docker/docker-compose.production.yml` — legacy config
See `make/config.mk` for COMPOSE_PROD and deployment docs. See `make/config.mk` for COMPOSE_PROD and deployment docs.
## CI/CD ## CI/CD

47
k8s/disaster-recovery/runbooks/cluster-failover.md
View file

@ -107,7 +107,7 @@ kubectl exec -it postgres-pod -n veza-production -- \
### Step 4: Deploy Applications ### Step 4: Deploy Applications
```bash ```bash
# Deploy backend API # Deploy backend API (includes chat since v0.502 merge)
kubectl apply -f k8s/backend-api/deployment.yaml -n veza-production kubectl apply -f k8s/backend-api/deployment.yaml -n veza-production
kubectl apply -f k8s/backend-api/service.yaml -n veza-production kubectl apply -f k8s/backend-api/service.yaml -n veza-production
@ -115,14 +115,14 @@ kubectl apply -f k8s/backend-api/service.yaml -n veza-production
kubectl apply -f k8s/frontend/deployment.yaml -n veza-production kubectl apply -f k8s/frontend/deployment.yaml -n veza-production
kubectl apply -f k8s/frontend/service.yaml -n veza-production kubectl apply -f k8s/frontend/service.yaml -n veza-production
# Deploy chat server # Deploy stream server
kubectl apply -f k8s/chat-server/deployment.yaml -n veza-production kubectl apply -f k8s/stream-server/deployment.yaml -n veza-production
kubectl apply -f k8s/chat-server/service.yaml -n veza-production kubectl apply -f k8s/stream-server/service.yaml -n veza-production
# Wait for deployments # Wait for deployments
kubectl rollout status deployment/veza-backend-api -n veza-production kubectl rollout status deployment/veza-backend-api -n veza-production
kubectl rollout status deployment/veza-frontend -n veza-production kubectl rollout status deployment/veza-frontend -n veza-production
kubectl rollout status deployment/veza-chat-server -n veza-production kubectl rollout status deployment/veza-stream-server -n veza-production
``` ```
### Step 5: Configure Ingress ### Step 5: Configure Ingress
@ -213,38 +213,38 @@ kubectl delete pod redis-pod -n veza-production # Restart to load backup
### Immediate (First Hour) ### Immediate (First Hour)
1. **Monitor Platform** 1. **Monitor Platform**
- Watch application logs - Watch application logs
- Monitor error rates - Monitor error rates
- Check performance metrics - Check performance metrics
2. **Notify Stakeholders** 2. **Notify Stakeholders**
- Send status update - Send status update
- Update status page - Update status page
- Communicate expected timeline - Communicate expected timeline
### Short Term (First Day) ### Short Term (First Day)
1. **Investigate Primary Cluster** 1. **Investigate Primary Cluster**
- Assess damage - Assess damage
- Identify root cause - Identify root cause
- Estimate recovery time - Estimate recovery time
2. **Optimize DR Cluster** 2. **Optimize DR Cluster**
- Scale resources if needed - Scale resources if needed
- Optimize configurations - Optimize configurations
- Monitor performance - Monitor performance
### Long Term (Recovery Phase) ### Long Term (Recovery Phase)
1. **Restore Primary Cluster** 1. **Restore Primary Cluster**
- Fix issues in primary - Fix issues in primary
- Restore from backups - Restore from backups
- Verify functionality - Verify functionality
2. **Plan Failback** 2. **Plan Failback**
- Schedule maintenance window - Schedule maintenance window
- Prepare failback procedure - Prepare failback procedure
- Test failback process - Test failback process
## Failback Procedure ## Failback Procedure
@ -318,4 +318,3 @@ kubectl get ingress veza-ingress -n veza-production
- [Database Restore Runbook](./data-restore.md) - [Database Restore Runbook](./data-restore.md)
- [Kubernetes Multi-Cluster Setup](https://kubernetes.io/docs/setup/) - [Kubernetes Multi-Cluster Setup](https://kubernetes.io/docs/setup/)
- [DNS Management Best Practices](../README.md) - [DNS Management Best Practices](../README.md)

31
k8s/disaster-recovery/runbooks/data-restore.md
View file

@ -58,8 +58,8 @@ aws s3 ls s3://veza-backups/postgres/ --recursive | sort
```bash ```bash
# Scale down applications to prevent writes # Scale down applications to prevent writes
# (backend-api handles chat since v0.502 merge — no separate chat-server deployment)
kubectl scale deployment veza-backend-api --replicas=0 -n veza-production kubectl scale deployment veza-backend-api --replicas=0 -n veza-production
kubectl scale deployment veza-chat-server --replicas=0 -n veza-production
# Verify pods are stopped # Verify pods are stopped
kubectl get pods -n veza-production -l app=veza-backend-api kubectl get pods -n veza-production -l app=veza-backend-api
@ -201,13 +201,11 @@ kubectl exec -it postgres-pod -n veza-production -- \
### Step 6: Restart Applications ### Step 6: Restart Applications
```bash ```bash
# Scale up applications # Scale up applications (backend-api handles chat since v0.502)
kubectl scale deployment veza-backend-api --replicas=3 -n veza-production kubectl scale deployment veza-backend-api --replicas=3 -n veza-production
kubectl scale deployment veza-chat-server --replicas=2 -n veza-production
# Wait for pods to be ready # Wait for pods to be ready
kubectl rollout status deployment/veza-backend-api -n veza-production kubectl rollout status deployment/veza-backend-api -n veza-production
kubectl rollout status deployment/veza-chat-server -n veza-production
``` ```
### Step 7: Verify Application Functionality ### Step 7: Verify Application Functionality
@ -310,27 +308,26 @@ kubectl exec -it postgres-pod -n veza-production -- \
## Post-Restore Tasks ## Post-Restore Tasks
1. **Monitor Platform** 1. **Monitor Platform**
- Watch application logs - Watch application logs
- Monitor error rates - Monitor error rates
- Check performance metrics - Check performance metrics
2. **Verify Data** 2. **Verify Data**
- Run data integrity checks - Run data integrity checks
- Compare with expected values - Compare with expected values
- Test critical user flows - Test critical user flows
3. **Document Incident** 3. **Document Incident**
- Document restore procedure - Document restore procedure
- Note any issues encountered - Note any issues encountered
- Update runbook if needed - Update runbook if needed
4. **Investigate Root Cause** 4. **Investigate Root Cause**
- Review logs and events - Review logs and events
- Identify what caused data loss - Identify what caused data loss
- Implement prevention measures - Implement prevention measures
## References ## References
- [Backup Strategy](../backups/README.md) - [Backup Strategy](../backups/README.md)
- [PostgreSQL Restore Documentation](https://www.postgresql.org/docs/current/app-pgrestore.html) - [PostgreSQL Restore Documentation](https://www.postgresql.org/docs/current/app-pgrestore.html)

28
k8s/disaster-recovery/runbooks/database-failover.md
View file

@ -14,6 +14,7 @@ This runbook describes the procedure for failing over from a primary PostgreSQL
### Automatic Detection ### Automatic Detection
Monitoring alerts will trigger when: Monitoring alerts will trigger when:
- Primary database is unreachable - Primary database is unreachable
- Replication lag exceeds threshold - Replication lag exceeds threshold
- Health checks fail - Health checks fail
@ -75,8 +76,8 @@ kubectl get pod postgres-standby -n veza-production -o jsonpath='{.metadata.labe
```bash ```bash
# Restart to pick up new database connection # Restart to pick up new database connection
# (backend-api handles chat since v0.502 merge — no separate chat-server deployment)
kubectl rollout restart deployment/veza-backend-api -n veza-production kubectl rollout restart deployment/veza-backend-api -n veza-production
kubectl rollout restart deployment/veza-chat-server -n veza-production
# Verify pods are healthy # Verify pods are healthy
kubectl rollout status deployment/veza-backend-api -n veza-production kubectl rollout status deployment/veza-backend-api -n veza-production
@ -161,27 +162,26 @@ kubectl run test-connection --rm -it --image=postgres:15-alpine \
## Post-Failover Tasks ## Post-Failover Tasks
1. **Investigate Root Cause** 1. **Investigate Root Cause**
- Review primary database logs - Review primary database logs
- Check system resources - Check system resources
- Identify failure reason - Identify failure reason
2. **Set Up New Standby** 2. **Set Up New Standby**
- Configure replication from new primary - Configure replication from new primary
- Verify synchronization - Verify synchronization
- Update monitoring - Update monitoring
3. **Document Incident** 3. **Document Incident**
- Document failover procedure - Document failover procedure
- Note any issues encountered - Note any issues encountered
- Update runbook if needed - Update runbook if needed
4. **Notify Stakeholders** 4. **Notify Stakeholders**
- Send incident report - Send incident report
- Update status page - Update status page
- Schedule post-mortem - Schedule post-mortem
## References ## References
- [PostgreSQL Replication Documentation](https://www.postgresql.org/docs/current/high-availability.html) - [PostgreSQL Replication Documentation](https://www.postgresql.org/docs/current/high-availability.html)
- [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/) - [Kubernetes Service Documentation](https://kubernetes.io/docs/concepts/services-networking/service/)

34
k8s/disaster-recovery/runbooks/rollback-procedure.md
View file

@ -13,6 +13,7 @@ This runbook describes the procedure for rolling back a failed application deplo
### Automatic Detection ### Automatic Detection
Health checks will automatically detect: Health checks will automatically detect:
- Application crashes - Application crashes
- High error rates - High error rates
- Slow response times - Slow response times
@ -124,19 +125,19 @@ kubectl top pods -n veza-production
If multiple services need rollback: If multiple services need rollback:
```bash ```bash
# Rollback backend API # Rollback backend API (handles chat since v0.502 merge)
kubectl rollout undo deployment/veza-backend-api -n veza-production kubectl rollout undo deployment/veza-backend-api -n veza-production
# Rollback frontend # Rollback frontend
kubectl rollout undo deployment/veza-frontend -n veza-production kubectl rollout undo deployment/veza-frontend -n veza-production
# Rollback chat server # Rollback stream server (if media layer affected)
kubectl rollout undo deployment/veza-chat-server -n veza-production kubectl rollout undo deployment/veza-stream-server -n veza-production
# Monitor all rollbacks # Monitor all rollbacks
kubectl rollout status deployment/veza-backend-api -n veza-production kubectl rollout status deployment/veza-backend-api -n veza-production
kubectl rollout status deployment/veza-frontend -n veza-production kubectl rollout status deployment/veza-frontend -n veza-production
kubectl rollout status deployment/veza-chat-server -n veza-production kubectl rollout status deployment/veza-stream-server -n veza-production
``` ```
## Database Migration Rollback ## Database Migration Rollback
@ -219,24 +220,24 @@ kubectl logs <pod-name> -n veza-production
## Post-Rollback Tasks ## Post-Rollback Tasks
1. **Investigate Root Cause** 1. **Investigate Root Cause**
- Review deployment logs - Review deployment logs
- Check application logs - Check application logs
- Identify what caused failure - Identify what caused failure
2. **Fix Issue** 2. **Fix Issue**
- Address root cause - Address root cause
- Test fix in staging - Test fix in staging
- Prepare new deployment - Prepare new deployment
3. **Document Incident** 3. **Document Incident**
- Document rollback procedure - Document rollback procedure
- Note any issues encountered - Note any issues encountered
- Update deployment process if needed - Update deployment process if needed
4. **Notify Stakeholders** 4. **Notify Stakeholders**
- Send incident report - Send incident report
- Update status page - Update status page
- Schedule post-mortem if needed - Schedule post-mortem if needed
## Prevention ## Prevention
@ -252,4 +253,3 @@ To prevent future rollbacks:
- [Kubernetes Rollout Documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-back-a-deployment) - [Kubernetes Rollout Documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-back-a-deployment)
- [Deployment Best Practices](../README.md) - [Deployment Best Practices](../README.md)

30
k8s/network-policies/README.md
View file

@ -4,26 +4,28 @@ Network policies restrict traffic between pods for defense in depth.
## Dependencies ## Dependencies
| Service | Ingress From | Egress To | | Service | Ingress From | Egress To |
|---------------|-------------------|------------------------------| | ------------- | ------------- | ------------------------------------ |
| backend-api | ingress-nginx | PostgreSQL (5432), Redis (6379), DNS | | backend-api | ingress-nginx | PostgreSQL (5432), Redis (6379), DNS |
| frontend | ingress-nginx | - | | frontend | ingress-nginx | - |
| chat-server | ingress-nginx | PostgreSQL (5432), Redis (6379), DNS | | stream-server | ingress-nginx | Redis, storage |
| stream-server | ingress-nginx | Redis, storage |
<!-- chat-server was merged into backend-api in v0.502 (commit 05d02386d) -->
<!-- Chat traffic now uses backend-api ingress on /api/v1/ws -->
## Usage ## Usage
1. Apply default deny first: 1. Apply default deny first:
```bash
kubectl apply -f k8s/network-policies/default-deny.yaml ```bash
``` kubectl apply -f k8s/network-policies/default-deny.yaml
```
2. Apply allow policies for each component: 2. Apply allow policies for each component:
```bash ```bash
kubectl apply -f k8s/network-policies/backend-api-allow.yaml kubectl apply -f k8s/network-policies/backend-api-allow.yaml
kubectl apply -f k8s/network-policies/frontend-allow.yaml kubectl apply -f k8s/network-policies/frontend-allow.yaml
kubectl apply -f k8s/network-policies/chat-server-allow.yaml ```
```
## Ingress Controller ## Ingress Controller

4
k8s/secrets.yaml.example
View file

@ -24,8 +24,8 @@ stringData:
s3-access-key: "your_aws_access_key" s3-access-key: "your_aws_access_key"
s3-secret-key: "your_aws_secret_key" s3-secret-key: "your_aws_secret_key"
# Chat Server secrets # Chat: merged into backend-api since v0.502 (commit 05d02386d)
chat-server-secret: "your_chat_server_secret" # Reuses the shared JWT secret — no separate chat-server secret.
# Stream Server secrets # Stream Server secrets
stream-server-secret: "your_stream_server_secret" stream-server-secret: "your_stream_server_secret"

116
k8s/secrets/README.md
View file

@ -73,6 +73,7 @@ kubectl apply -f k8s/secrets/external-secrets/veza-secrets.yaml
### HashiCorp Vault ### HashiCorp Vault
Vault provides enterprise-grade secrets management with: Vault provides enterprise-grade secrets management with:
- Automatic secret rotation - Automatic secret rotation
- Audit logging - Audit logging
- Fine-grained access control - Fine-grained access control
@ -132,32 +133,29 @@ kubectl apply -f k8s/secrets/external-secrets/veza-secrets-gcp.yaml
All Veza services require the following secrets: All Veza services require the following secrets:
| Secret Key | Description | Example | | Secret Key | Description | Example |
|------------|-------------|---------| | -------------- | --------------------------------- | ------------------------------------------------------- |
| `database-url` | PostgreSQL connection string | `postgresql://user:pass@host:5432/veza?sslmode=require` | | `database-url` | PostgreSQL connection string | `postgresql://user:pass@host:5432/veza?sslmode=require` |
| `redis-url` | Redis connection string | `redis://host:6379/0` | | `redis-url` | Redis connection string | `redis://host:6379/0` |
| `jwt-secret` | JWT signing secret (min 32 chars) | `your-super-secret-jwt-key-min-32-chars-long` | | `jwt-secret` | JWT signing secret (min 32 chars) | `your-super-secret-jwt-key-min-32-chars-long` |
### Backend API Additional Secrets ### Backend API Additional Secrets
| Secret Key | Description | Example | | Secret Key | Description | Example |
|------------|-------------|---------| | ----------------------- | ----------------------------- | ------------- |
| `stripe-api-key` | Stripe API key for payments | `sk_live_...` | | `stripe-api-key` | Stripe API key for payments | `sk_live_...` |
| `stripe-webhook-secret` | Stripe webhook signing secret | `whsec_...` | | `stripe-webhook-secret` | Stripe webhook signing secret | `whsec_...` |
| `smtp-password` | SMTP password for emails | `password` | | `smtp-password` | SMTP password for emails | `password` |
| `s3-access-key` | AWS S3 access key | `AKIA...` | | `s3-access-key` | AWS S3 access key | `AKIA...` |
| `s3-secret-key` | AWS S3 secret key | `...` | | `s3-secret-key` | AWS S3 secret key | `...` |
### Chat Server Additional Secrets <!-- Chat Server section removed: merged into backend-api at commit 05d02386d (v0.502). -->
<!-- Chat now uses the same JWT secret as backend-api. -->
| Secret Key | Description | Example |
|------------|-------------|---------|
| `chat-server-secret` | Secret for chat server authentication | `chat-secret-key` |
### Stream Server Additional Secrets ### Stream Server Additional Secrets
| Secret Key | Description | Example | | Secret Key | Description | Example |
|------------|-------------|---------| | ---------------------- | --------------------------------------- | ------------------- |
| `stream-server-secret` | Secret for stream server authentication | `stream-secret-key` | | `stream-server-secret` | Secret for stream server authentication | `stream-secret-key` |
## Environment-Specific Secrets ## Environment-Specific Secrets
@ -225,42 +223,43 @@ kubectl apply -f k8s/secrets/secrets-rotation.yaml
## Security Best Practices ## Security Best Practices
1. **Never commit secrets to Git** 1. **Never commit secrets to Git**
- Use `.gitignore` for secret files - Use `.gitignore` for secret files
- Use `secrets.yaml.example` as template - Use `secrets.yaml.example` as template
2. **Use separate secrets per environment** 2. **Use separate secrets per environment**
- Different secrets for dev, staging, production - Different secrets for dev, staging, production
- Use namespaces to isolate environments - Use namespaces to isolate environments
3. **Rotate secrets regularly** 3. **Rotate secrets regularly**
- JWT secrets: Every 90 days - JWT secrets: Every 90 days
- Database passwords: Every 180 days - Database passwords: Every 180 days
- API keys: As per provider recommendations - API keys: As per provider recommendations
4. **Limit access with RBAC** 4. **Limit access with RBAC**
```yaml
apiVersion: rbac.authorization.k8s.io/v1 ```yaml
kind: Role apiVersion: rbac.authorization.k8s.io/v1
metadata: kind: Role
name: secrets-reader metadata:
namespace: veza-production name: secrets-reader
rules: namespace: veza-production
- apiGroups: [""] rules:
resources: ["secrets"] - apiGroups: [""]
verbs: ["get", "list"] resources: ["secrets"]
``` verbs: ["get", "list"]
```
5. **Enable audit logging** 5. **Enable audit logging**
- Log all secret access - Log all secret access
- Monitor for unauthorized access - Monitor for unauthorized access
6. **Use encryption at rest** 6. **Use encryption at rest**
- Enable encryption for etcd (Kubernetes secrets) - Enable encryption for etcd (Kubernetes secrets)
- Use encrypted volumes for Vault - Use encrypted volumes for Vault
7. **Principle of least privilege** 7. **Principle of least privilege**
- Only grant access to secrets that are needed - Only grant access to secrets that are needed
- Use service accounts with minimal permissions - Use service accounts with minimal permissions
## Troubleshooting ## Troubleshooting
@ -306,25 +305,29 @@ kubectl describe serviceaccount veza-backend-api -n veza-production
### From Kubernetes Secrets to External Secrets ### From Kubernetes Secrets to External Secrets
1. **Install External Secrets Operator** 1. **Install External Secrets Operator**
```bash
kubectl apply -f k8s/secrets/external-secrets-operator.yaml ```bash
``` kubectl apply -f k8s/secrets/external-secrets-operator.yaml
```
2. **Configure secret store** 2. **Configure secret store**
```bash
kubectl apply -f k8s/secrets/secret-stores/vault-store.yaml ```bash
``` kubectl apply -f k8s/secrets/secret-stores/vault-store.yaml
```
3. **Create ExternalSecret resources** 3. **Create ExternalSecret resources**
```bash
kubectl apply -f k8s/secrets/external-secrets/veza-secrets.yaml ```bash
``` kubectl apply -f k8s/secrets/external-secrets/veza-secrets.yaml
```
4. **Verify secrets are synced** 4. **Verify secrets are synced**
```bash
kubectl get externalsecret -n veza-production ```bash
kubectl get secret veza-secrets -n veza-production kubectl get externalsecret -n veza-production
``` kubectl get secret veza-secrets -n veza-production
```
5. **Update deployments** (if needed, External Secrets creates the same secret name) 5. **Update deployments** (if needed, External Secrets creates the same secret name)
@ -337,4 +340,3 @@ kubectl describe serviceaccount veza-backend-api -n veza-production
- [Kubernetes Secrets Documentation](https://kubernetes.io/docs/concepts/configuration/secret/) - [Kubernetes Secrets Documentation](https://kubernetes.io/docs/concepts/configuration/secret/)
- [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) - [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/)
- [Google Cloud Secret Manager](https://cloud.google.com/secret-manager) - [Google Cloud Secret Manager](https://cloud.google.com/secret-manager)