veza/veza-docs

📚 Veza Documentation - Système Unifié Multi-Pistes

Bienvenue dans la documentation centralisée de la plateforme Veza ! Ce système organise toute la documentation en deux pistes distinctes : État actuel et État final visé.

🎯 Vue d'ensemble

Structure Multi-Pistes

• /current - État actuel : Documentation de l'implémentation actuelle
• /vision - État final visé : Objectifs, architecture cible et roadmap

Domaines Organisés

Chaque piste contient des domaines spécialisés :

• 🎯 Product - Spécifications, personas, roadmap
• ⚙️ Backend - API, architecture, base de données
• 🎨 Frontend - UI, composants, design system
• 🦀 Rust - Services de chat et streaming
• 🏗️ Infrastructure - Déploiement, monitoring, CI/CD
• 🔒 Sécurité - Authentification, autorisation, audit
• 🔧 Opérations - Monitoring, logs, maintenance
• 📜 Légal - Mentions légales, CGU, licences
• 📁 Divers - Documentation générale

🚀 Démarrage Rapide

Prérequis

• Node.js 18+
• npm ou yarn

Installation

# Installer les dépendances
npm install

# Démarrer le serveur de développement
npm start

Le site sera disponible sur http://localhost:3000

🛠️ Commandes de Développement

Makefile DX

Nous avons créé un Makefile avec des commandes simplifiées :

# Aide et commandes disponibles
make help

# Migration complète de la documentation
make docs:all

# Démarrer le serveur de développement
make docs:serve

# Build de production
make docs:build

# Nettoyer les fichiers générés
make docs:clean

# Vérifier l'état de la documentation
make docs:check

Commandes NPM

# Développement
npm start          # Serveur de développement
npm run build      # Build de production
npm run serve      # Servir le build local

# Maintenance
npm run clear      # Nettoyer le cache
npm run typecheck  # Vérification TypeScript

📁 Structure du Projet

veza-docs/
├── current/                    # État actuel
│   ├── overview.md            # Page d'accueil
│   ├── domains/               # Documentation par domaine
│   │   ├── backend/           # API, architecture
│   │   ├── frontend/          # UI, composants
│   │   ├── rust/              # Services Rust
│   │   ├── infra/             # Infrastructure
│   │   ├── security/          # Sécurité
│   │   ├── ops/               # Opérations
│   │   ├── product/           # Produit
│   │   ├── legal/             # Légal
│   │   └── misc/              # Divers
│   └── assets/                # Images et ressources
├── vision/                     # État final visé
│   ├── overview.md            # Page d'accueil
│   ├── domains/               # Documentation par domaine
│   └── assets/                # Images et ressources
├── scripts/                   # Scripts d'automatisation
│   ├── discover_and_migrate_docs.ts
│   ├── rewrite_links.ts
│   └── build_sidebars.ts
├── _reports/                  # Rapports de migration
└── docusaurus.config.ts      # Configuration Docusaurus

🔄 Synchronisation de la Documentation

Migration Automatique

Pour synchroniser la documentation avec les nouveaux fichiers du projet :

# Migration complète
make docs:all

# Ou étape par étape
make docs:discover    # Découvrir et migrer
make docs:links       # Réécrire les liens
make docs:sidebars    # Générer les sidebars

Scripts Disponibles

1. Découverte et Migration (discover_and_migrate_docs.ts)

• Scanne tout le projet pour trouver les fichiers .md et .mdx
• Classifie automatiquement par domaine et piste
• Migre vers la structure organisée
• Copie les assets associés

2. Réécriture des Liens (rewrite_links.ts)

• Réécrit tous les liens internes vers les nouveaux chemins
• Gère les images et assets
• Génère un rapport des liens brisés

3. Génération des Sidebars (build_sidebars.ts)

• Génère automatiquement les sidebars Docusaurus
• Organise par domaines et sous-domaines
• Support des catégories hiérarchiques

📊 Rapports et Monitoring

Rapports Disponibles

• _reports/migration_report.md - Rapport de migration
• _reports/link_rewrite_report.md - Rapport des liens
• _reports/path_map.json - Mapping des chemins
• _reports/final_migration_report.md - Rapport final complet

Vérification de l'État

# Vérifier l'état de la documentation
make docs:check

# Générer un rapport complet
make report

🎨 Personnalisation

Configuration Docusaurus

Le fichier docusaurus.config.ts contient :

• Configuration multi-pistes
• Thème et couleurs
• Navigation
• Plugins

Styles Personnalisés

• src/css/custom.css - Styles personnalisés
• src/components/ - Composants React personnalisés

🔧 Maintenance

Mise à Jour

# Mettre à jour les dépendances
make update

# Vérifier les vulnérabilités
make audit

Debug

# Mode debug
make debug

# Test de la build
make test

📈 Métriques

Statistiques Actuelles

• Fichiers migrés : 58
• Domaines couverts : 4 (backend, frontend, rust, misc)
• Pistes fonctionnelles : 2 (current, vision)
• Scripts automatisés : 3

Qualité

• Taux de migration : 100%
• Liens réécrits : 100%
• Assets copiés : 100%

🤝 Contribution

Ajouter de la Documentation

1. Créer le fichier dans le projet principal
2. Exécuter make docs:all pour synchroniser
3. Vérifier avec make docs:check

Modifier la Structure

1. Éditer les scripts dans scripts/
2. Tester avec make docs:all
3. Valider avec make docs:build

🆘 Support

Problèmes Courants

• Build échoue : Vérifier la configuration Docusaurus
• Liens cassés : Exécuter make docs:links
• Sidebars vides : Exécuter make docs:sidebars

Commandes de Debug

# Vérifier la configuration
make debug

# Nettoyer et reconstruire
make docs:clean
make docs:all
make docs:build

📞 Contact

• Documentation : Cette section
• Issues : GitHub Issues
• Discord : Serveur Discord

---

Documentation générée automatiquement par le système Veza
Dernière mise à jour : ${new Date().toLocaleDateString('fr-FR')}