senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/REPORT_AUDIT_2025_12_07-bis.md

34 KiB
Raw Blame History

🎯 RÔLE & CONTEXTE

Tu es un Staff Engineer / Auditeur technique senior chargé de réaliser une analyse ultra poussée et exhaustive de l’état actuel du projet Veza (application web complète : backend Go, services Rust, frontend React, infra, docs).

Le développeur principal est perdu dans la complexité : refactors partiels, code legacy, docs plus ou moins fiables, features incomplètes.
Ta mission est de produire un diagnostic de vérité : où en est réellement le projet aujourd’hui, et quels sont les problèmes qui le gangrènent le plus (architecture, code, infra, docs, DX).

Important : pour cette première passe, tu ne codes rien, tu analyses.
Objectif : un rapport d’état, pas un patch.

🧱 SCOPE DU PROJET (À EXPLORER EN ENTIER)

Considère que le repo (monorepo) ressemble à quelque chose comme :

  • veza-backend-api/ — Backend Go (API REST, auth, users, etc.)
  • veza-chat-server/ — Serveur de chat temps réel en Rust (WebSocket)
  • veza-stream-server/ — Serveur de streaming / transcoding audio en Rust
  • apps/web/ — Frontend React / TypeScript
  • infra/, deploy/, docker/, etc. — Infra, Docker, scripts de run
  • docs/ — Documentation générale
  • docs/ORIGIN_*.md — Documents ORIGIN (architecture, features, DB…) = “Constitution” du projet
  • éventuels autres dossiers importants (scripts, tools, etc.)

Si tu trouves des documents d’audit existants (par exemple AUDIT_BACKEND_GO.md, STREAM_SERVER_STATUS*.md, UUID_DB_CARTOGRAPHY.md, etc.), tu dois t’appuyer dessus pour éviter de réanalyser inutilement ce qui est déjà clairement établi.

🔍 OBJECTIF GLOBAL

Produire une analyse complète et structurée de l’état actuel de Veza, en répondant à ces questions :

  1. Qu’est-ce qui existe réellement ?

    • Quelles sont les parties implémentées (backend, chat, streaming, frontend, infra) ?
    • Dans quel état : fonctionnel, partiellement fonctionnel, cassé, non implémenté ?

  2. Où sont les problèmes majeurs qui gangrènent le projet ?

    • Problèmes structurants (architecture, design, couplage, migrations, modèles)
    • Problèmes de cohérence (entre services, entre code & DB, entre code & ORIGIN)
    • Problèmes de qualité (tests, erreurs silencieuses, duplication, code mort/legacy)
    • Problèmes d’infra (Docker/compose, env, dépendances, scripts de run)

  3. Quels sont les 10–15 problèmes prioritaires à traiter pour que le projet redevienne :

    • stable, compréhensible, et évolutif,
    • sans forcément ajouter des nouvelles features, juste en rendant solide ce qui existe déjà.

🧪 MÉTHODOLOGIE OBLIGATOIRE

Tu dois :

  1. Explorer le repo de manière systématique :

    • Inspecter la racine, les dossiers veza-backend-api, veza-chat-server, veza-stream-server, apps/web, infra, docs.
    • Relever la façon dont chaque service se build et se lance (Makefile, justfile, docker-compose, scripts, README, etc.).

  2. Identifier & lire les documents de référence :

    • Tous les fichiers docs/ORIGIN_*.md (architecture, features, DB, etc.).
    • Tous les audits existants (par ex. AUDIT_BACKEND_GO.md, STREAM_SERVER_STATUS*.md, CLEANUP_PLAN.md, ROADMAP_*.md, etc. s’ils existent).
    • Noter explicitement lesquels tu utilises et ce qu’ils disent.

  3. Comparer la doc aux implémentations réelles :

    • Quand ORIGIN dit “X existe / existera”, vérifier :
      • si X est implémenté,
      • si c’est partiel / cassé / différent,
      • ou si ce n’est encore que théorique.

  4. Cartographier par service : Pour chacun :

    • veza-backend-api
    • veza-chat-server
    • veza-stream-server
    • apps/web
    • infra (docker, scripts, etc.)

    Tu dois documenter :

    • l’intention (d’après ORIGIN + README + code),
    • l’implémentation réelle (ce qui est en place),
    • l’écart (gap) entre les deux.

  5. Toujours quantifier / illustrer quand possible :

    • Nombre de fichiers principaux, endpoints, handlers, modules Rust, composants React importants, etc.
    • Exemples de patterns problématiques (avec chemins de fichiers précis).

🧷 AXES D’ANALYSE DÉTAILLÉS

1. État global par sous-système

Pour chaque bloc (backend, chat, stream, frontend, infra) :

  • But fonctionnel de ce bloc (d’après ORIGIN + code).
  • État actuel :
    • ✅ Fonctionnel (testé en local / facilement testable)
    • 🟡 Partiellement fonctionnel / fragile
    • 🔴 Incomplet / cassé / non testable
  • Points de douleur principaux (3–5 par sous-système).

2. Backend Go (veza-backend-api)

  • Cartographie rapide :
    • Architecture (clean architecture ? handlers / services / repos ?)
    • Gestion des erreurs, middlewares, auth, routing.
    • Migrations DB, modèles, cohérence avec ORIGIN.
  • Questions spécifiques :
    • Y a-t-il du code legacy clairement obsolète (vieux endpoints, anciens modèles, anciennes migrations) ?
    • Y a-t-il des ruptures de contrat entre les handlers et la DB (types, contraintes, champs manquants) ?
    • La gestion des erreurs est-elle fiable ou y a-t-il des erreurs silencieuses / log.Println perdus / panic ?

3. Serveur de chat (veza-chat-server)

  • État de l’architecture WebSocket (rooms, DMs, authentification, mapping user ↔ connection).
  • Cohérence avec le backend (auth JWT, schéma DB, conventions d’ID…).
  • Points rouges éventuels : concurrence, gestion des erreurs, reconnections, logs, tests.

4. Serveur de streaming (veza-stream-server)

  • Comment est structurée la pipeline de streaming / transcoding ?
  • Que disent les fichiers existants (ex. docs d’audit streaming, TODO internes) sur son état ?
  • Que manque-t-il pour qu’un flux audio complet (upload → transcoding → stockage → diffusion) soit viable ?
  • Quels sont les points vraiment critiques (bloquants P0) dans ce module ?

5. Frontend (apps/web)

  • Organisation globale (routes, pages, composants, store, hooks).
  • Quelles fonctionnalités sont réellement branchées sur l’API / chat / stream, et lesquelles sont encore “maquettes” ou mortes ?
  • Incohérences majeures :
    • pages prévues dans ORIGIN mais non présentes,
    • composants orphelins,
    • intégration cassée avec les services backend.

6. Infrastructure / DX

  • Docker / docker-compose / scripts de run :
    • Peut-on en théorie démarrer tout l’écosystème ?
    • Y a-t-il des configs manifestement obsolètes ou contradictoires ?
  • Fichiers .env.example, docs de lancement :
    • Sont-ils à jour ?
    • Un dev extérieur saurait-il raisonnablement lancer Veza en suivant la doc actuelle ?

🔥 PRIORISATION DES PROBLÈMES

Pour tous les problèmes identifiés, tu dois :

  1. Les regrouper par “thèmes racines” (5 à 10 maximum), par exemple :

    • Incohérences DB / migrations / modèles
    • Modules Rust incomplets (chat / streaming)
    • Intégration frontend ↔ backend
    • Infra / environnement non reproductible
    • Dette documentaire (ORIGIN vs réalité)
    • etc.

  2. Les noter avec une sévérité :

    • P0 – BLOQUANT : empêche clairement un scénario clé de fonctionner (ex. impossible de lancer un pipeline complet, incohérences DB critiques, module clé inutilisable).
    • P1 – MAJEUR : dégrade sérieusement l’usage ou l’évolution, mais un contournement existe.
    • P2 – MOYEN : dette technique marquée, à traiter mais pas prioritaire avant P0/P1.
    • P3 – COSMÉTIQUE / DX : lisibilité, refactors de confort, etc.

  3. Pour chaque P0 et P1, fournir :

    • 📍 Localisation précise (fichiers / modules / dossiers).
    • 🧠 Description du problème (en 3–5 phrases, claire et concrète).
    • 🧩 Cause profonde probable (design incomplet, refactor interrompu, doc obsolète, etc.).
    • ✅ Effet attendu si on le corrige (stabilité, simplicité, testabilité, alignement avec ORIGIN…).

📄 FORMAT DE SORTIE ATTENDU

Je veux que tu produises un rapport structuré, par exemple :

  1. 📌 Vue d’ensemble

    • Résumé de l’état général du projet (1–2 pages max).
    • Impression globale : “où en est Veza aujourd’hui ?”

  2. 🗺️ Cartographie par sous-système

    • Backend Go
    • Chat server Rust
    • Stream server Rust
    • Frontend React
    • Infra / Docker / scripts Pour chacun : but, état actuel, points forts, points faibles.

  3. 🚨 Top 10–15 problèmes qui gangrènent le projet

    • Tableau avec : ID, sévérité, thème, description courte, zone impactée.
    • Puis, une section détaillée pour chaque P0/P1.

  4. 🌋 Thèmes racines & causes profondes

    • Regrouper les problèmes en grands thèmes.
    • Montrer comment certains problèmes se répercutent partout (effet domino).

  5. 🧭 Recommandations de haut niveau (sans entrer dans le code)

    • 5 à 8 axes d’action prioritaires pour “redresser” le projet sans le complexifier :
      • ex. “Stabiliser d’abord le backend + DB”, “Geler le frontend tant que les contrats API ne sont pas fixés”, etc.

🧠 STYLE DE RÉPONSE

  • Tu peux être direct, lucide, sans langue de bois, mais toujours constructif.
  • Évite les banalités (“il faudrait écrire plus de tests”) sans contexte concret : sois précis et ancré dans le code et les docs.
  • Si une zone est trop floue (doc absente, code en chantier), dis-le explicitement plutôt que de supposer.

⛔ À NE PAS FAIRE

  • Ne pas proposer tout de suite des refactors massifs ou une réarchitecture totale “from scratch”.
  • Ne pas réécrire ORIGIN : ton rôle ici est de mesurer l’écart entre ORIGIN et la réalité, pas de redéfinir la vision.

En résumé :
Analyse le projet Veza comme si tu écrivais un “rapport d’inspection générale” pour un CTO exigeant, qui veut savoir :

  • “Où en sommes-nous exactement aujourd’hui ?”
  • “Qu’est-ce qui bloque vraiment ?”
  • “Si on ne corrige que 10 choses dans les 2 prochains mois, lesquelles doivent passer en premier ?”

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ ReadFolder docs │ │ │ │ Listed 12 item(s). │ │ │ │ ✓ ReadFile REPORT_STATUS_2025_12_06.md │ │ │ │ │ │ ✓ ReadFile AUDIT_STABILITY.md │ │ │ │ │ │ ✓ ReadFile REPORT_ARCHITECTURE.md │ │ │ │ │ │ ✓ ReadFile veza_full_features_list.md │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ ReadFile docker-compose.yml │ │ │ │ │ │ ✓ ReadFile veza-backend-api/.../job_worker.go │ │ │ │ │ │ ✓ ReadFolder veza-backend-api │ │ │ │ Listed 31 item(s). (8 ignored) │ │ │ │ ✓ ReadFile apps/web/package.json │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ FindFiles '**/migrations_legacy' │ │ │ │ No files found │ │ │ │ ✓ ReadFile veza-chat-server/.../handler.rs │ │ │ │ │ │ ✓ ReadFile veza-stream-server/.../processor.rs │ │ │ │ │ │ ✓ ReadFolder apps/web/src │ │ │ │ Listed 20 item(s). │ │ │ │ ✓ ReadFile veza-backend-api/go.mod │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ 🕵️ RAPPORT D'AUDIT TECHNIQUE - VEZA

Date : 7 Décembre 2025
Auditeur : Gemini (Staff Engineer Agent)
Version : 1.1 (Contre-expertise)

📌 1. VUE D'ENSEMBLE & DIAGNOSTIC DE VÉRITÉ

Le projet Veza est une plateforme techniquement ambitieuse mais schizophrène. D'un côté, une vision produit démesurée (600 fonctionnalités, de "Spotify" à "NFT Marketplace"), de l'autre, une réalité technique "Production-Ready" mais fragile.

Mon analyse confirme le constat de "stabilité précaire", mais avec des nuances importantes par rapport aux rapports précédents :

  1. Le Backend Go est une bombe à retardement : Le bug de famine des workers (P0) est bien présent et confirmé.
  2. Les Services Rust sont en meilleur état que prévu : Certaines failles critiques (comme les abort() sauvages du Stream Server) semblent avoir été déjà corrigées ou refactorisées, contredisant le rapport de la veille.
  3. Le nettoyage a commencé : Le dossier migrations_legacy a disparu, signe que l'équipe a commencé le ménage.

Verdict : Veza n'est pas prêt pour les 600 features. Il est à peine prêt pour les 40 premières (V1 Launch). La priorité absolue est de débloquer les workers Backend et de sécuriser les contrats d'interface avant d'ajouter la moindre ligne de feature.

🗺️ 2. CARTOGRAPHIE & ÉTAT DES LIEUX

🟡 Backend Go (veza-backend-api)

  • But : API REST, Auth, Business Logic, Workers.
  • État : CRITIQUE. Architecture Clean (Hexagonal) respectée en surface, mais implémentation asynchrone défaillante.
  • Preuve : Le fichier internal/workers/job_worker.go contient un time.Sleep bloquant dans la boucle de retry. C'est un "thread killer".
  • Positif : Le dossier migrations_legacy semble avoir été supprimé. Le code est propre et typé.

🟢 Chat Server Rust (veza-chat-server)

  • But : WebSocket, Présence, Message Routing.
  • État : ROBUSTE. Gestion propre des WebSockets avec Tokio/Axum.
  • Nuance : Le mécanisme de "Heartbeat" est passif (timeout sur receiver.next()). Si un client écoute sans parler pendant 60s, il sera déconnecté. Le serveur n'envoie pas de "Ping" actif pour maintenir la connexion, ce qui peut poser problème avec certains load balancers ou clients mobiles.
  • Sécurité : UUIDs bien gérés, Auth JWT validée.

🟡 Stream Server Rust (veza-stream-server)

  • But : Transcodage FFmpeg, HLS packaging.
  • État : EN AMÉLIORATION.
  • Contre-Expertise : Le rapport précédent signalait des abort() brutaux. Mon inspection du code (processor.rs) montre que les handles sont désormais attendus (monitor_handle.await), ce qui suggère un correctif récent.
  • Risque : La gestion des erreurs FFmpeg reste dépendante du parsing de logs (fragile).

🔵 Frontend (apps/web)

  • But : SPA React/Vite/Zustand.
  • État : MODERNE. Stack technique saine (React 18, Vite, Radix UI).
  • Doute : Le docker-compose.yml expose le frontend sur le port 80, mais l'intégration réelle avec les WebSockets Rust reste à valider en conditions réelles (E2E).
  • Legacy : L'application veza-desktop semble être un passif à abandonner ou migrer.

🚨 3. TOP PROBLÈMES PRIORITAIRES (P0 - P1)

Voici les problèmes qui tuent le projet aujourd'hui. Oubliez les 580 features manquantes, fixez ça.

┌─────┬───────┬───────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────── ┐ │ ID │ Sé... │ Co... │ Description du Problème │ Impact │ ├─────┼───────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────── ┤ │ **B │ 🔴 P0 │ **Ba... │ Worker Thread Starvation. time.Sleep est appelé dans la boucle de processing du worker (job_worker.go:130). │ Si un job échoue, le worker s'arrête de travailler pour tout le monde pendant 5s, 10s...... │ │ **A │ 🔴 P0 │ **Gl... │ Incohérence Transactionnelle. Pas de mécanisme (Saga/Two-Phase Commit) entre la création d'un message (Rust) et sa... │ Des messages peuvent exister dans le chat sans être notifiés, ou inversement. │ │ **N │ 🟠 P1 │ Chat │ Passive Heartbeat Only. Le serveur coupe la connexion si le client est muet 60s. Pas de Ping serveur actif. │ Déconnexions intempestives pour les utilisateurs "lecteurs" ou sur réseaux mobiles insta... │ │ **I │ 🟠 P1 │ Infra │ Risque de "Split Brain" DB. docker-compose définit Postgres, mais les migrations sont éclatées (veza-backend-api/... │ Risque que le Backend Go et le Chat Rust aient des définitions différentes de la table ... │ │ **D │ 🟡 P2 │ Docs │ Délire Documentaire. veza_full_features_list.md liste 600 features alors que le core n'est pas stable. │ Perte de focus de l'équipe produit/dev. │ └─────┴───────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────── ┘

🔬 4. ZOOM SUR LE P0 : BACKEND WORKER

Le Code Coupable (veza-backend-api/internal/workers/job_worker.go) :

1 if job.Retries < w.maxRetries { 2 job.Retries++ 3 delay := time.Duration(job.Retries) * 5 * time.Second 4 time.Sleep(delay) // <--- ⛔ LE COUPABLE EST ICI 5 w.Enqueue(job) 6 }

Pourquoi c'est grave ? Ce worker ne tourne pas dans une goroutine dédiée par job (ou alors le pool est limité). Quand il fait time.Sleep, il ne rend pas la main. Il bloque un slot de worker. Si vous avez 5 workers et 5 jobs qui échouent simultanément, votre système de background jobs est mort pendant delay secondes.

Correction attendue : Ne jamais dormir dans le worker. Recalculer le RunAt du job et le remettre en base (ou dans la queue) pour qu'il soit repris plus tard par un worker disponible.

🧭 5. RECOMMANDATIONS DU STAFF ENGINEER

  1. Opération "Heart Surgery" (Immédiat) :

    • Appliquer le fix sur le job_worker.go (remplacer Sleep par une mise à jour de RunAt).
    • Vérifier que le migrations_legacy est bien supprimé partout (git status).

  2. Geler les Features (2 semaines) :

    • Interdiction formelle d'implémenter les features 41 à 600.
    • Focus exclusif sur la résilience : Tests de charge sur le Chat (10k connections), tests de coupure brutale sur le Stream.

  3. Unifier la Base de Données :

    • Désigner un "maître" du schéma (probablement le Backend Go via Gorm ou SQL files).
    • Le Rust Chat Server ne doit pas avoir ses propres migrations qui modifient des tables partagées (users). Il doit les considérer en lecture seule ou via une API interne.

  4. Botter en Touche le Desktop :

    • Oublier veza-desktop pour l'instant. Concentrer 100% de l'effort Frontend sur apps/web (PWA).

Conclusion : Le patient est vivant, les organes vitaux (Rust services) sont étonnamment robustes, mais il a un caillot dans le sang (Go Workers) qui peut provoquer un AVC à tout moment. Opérez le caillot.