seo-generator-server/ARCHITECTURE_REFACTOR.md

🏗️ REFACTORISATION ARCHITECTURE - GÉNÉRATION PAR ÉTAPES

📁 NOUVELLE STRUCTURE FICHIERS

lib/
├── Main.js                          ← ORCHESTRATEUR PRINCIPAL
├── ContentGeneration.js             ← ORCHESTRATEUR GÉNÉRATION (4 étapes)
├── generation/
│   ├── InitialGeneration.js         ← ÉTAPE 1: Génération base (Claude)
│   ├── TechnicalEnhancement.js      ← ÉTAPE 2: Amélioration technique (GPT-4)
│   ├── TransitionEnhancement.js     ← ÉTAPE 3: Fluidité transitions (Gemini)
│   └── StyleEnhancement.js          ← ÉTAPE 4: Style personnalité (Mistral)
└── [autres fichiers existants...]

🎯 PRINCIPE D'ARCHITECTURE

1 FICHIER = 1 ÉTAPE = 1 RESPONSABILITÉ

• Chaque fichier a UN SEUL OBJECTIF
• Chaque fichier a UN LLM PRINCIPAL
• Chaque fichier TESTABLE INDÉPENDAMMENT

MAIN ENTRY POINT PAR FICHIER

Chaque fichier expose une fonction principale claire :

• InitialGeneration.js → generateInitialContent()
• TechnicalEnhancement.js → enhanceTechnicalTerms()
• TransitionEnhancement.js → enhanceTransitions()
• StyleEnhancement.js → applyPersonalityStyle()

🔄 FLUX D'ORCHESTRATION

Main.js:handleFullWorkflow()
    ↓
ContentGeneration.js:generateWithSelectiveEnhancement()
    ↓
InitialGeneration.js:generateInitialContent()      [Claude]
    ↓
TechnicalEnhancement.js:enhanceTechnicalTerms()    [GPT-4]
    ↓
TransitionEnhancement.js:enhanceTransitions()      [Gemini]
    ↓
StyleEnhancement.js:applyPersonalityStyle()        [Mistral]
    ↓
RÉSULTAT FINAL

📋 INTERFACES STANDARDISÉES

INPUT/OUTPUT CHAQUE ÉTAPE

// INPUT standardisé
{
  content: { "|tag1|": "contenu1", "|tag2|": "contenu2" },
  csvData: { mc0, t0, personality, ... },
  context: { step, totalSteps, metadata }
}

// OUTPUT standardisé
{
  content: { "|tag1|": "contenu_amélioré1", "|tag2|": "contenu_amélioré2" },
  stats: { processed: 15, enhanced: 8, duration: 2500 },
  debug: { llmProvider: "claude", tokens: 1200 }
}

⚡ AVANTAGES ARCHITECTURE

DÉVELOPPEMENT

• ✅ Debug par étape indépendante
• ✅ Tests unitaires par fichier
• ✅ Ajout/suppression d'étapes facile
• ✅ Code plus lisible et maintenable

PRODUCTION

• ✅ Bypass d'étapes si problème
• ✅ Monitoring précis par étape
• ✅ Optimisation performance individuelle
• ✅ Rollback par étape possible

🔧 MIGRATION PROGRESSIVE

PHASE 1: Créer nouvelle structure

• Créer dossier generation/ et fichiers
• Garder ancien code fonctionnel

PHASE 2: Migrer étape par étape

• InitialGeneration.js d'abord
• Puis TechnicalEnhancement.js
• Etc.

PHASE 3: Nettoyer ancien code

• Supprimer SelectiveEnhancement.js
• Mettre à jour imports

🎨 EXEMPLE STRUCTURE FICHIER

// generation/InitialGeneration.js
const { callLLM } = require('../LLMManager');
const { tracer } = require('../trace');

/**
 * ÉTAPE 1: GÉNÉRATION INITIALE
 * Responsabilité: Créer le contenu de base avec Claude
 * Input: hierarchy, csvData
 * Output: contenu généré initial
 */
async function generateInitialContent(hierarchy, csvData) {
  return await tracer.run('InitialGeneration.generateInitialContent()', async () => {
    // Logique génération initiale
    // Claude uniquement
  });
}

// Helper functions locales
function createBasePrompt() { /* ... */ }
function parseInitialResponse() { /* ... */ }

module.exports = {
  generateInitialContent,    // ← MAIN ENTRY POINT
  createBasePrompt,          // ← Helpers si besoin externe
  parseInitialResponse
};