4NK_IA_front/docs/architecture-backend.md

Architecture Backend pour le Traitement des Documents

Vue d'ensemble

L'application utilise maintenant une architecture backend qui traite les données (OCR, NER) et renvoie du JSON au frontend. Cette approche améliore les performances et centralise le traitement des documents.

Architecture

🏗️ Structure

4NK_IA_front/
├── backend/                 # Serveur backend Express
│   ├── server.js           # Serveur principal
│   ├── package.json        # Dépendances backend
│   └── uploads/            # Fichiers temporaires
├── src/                    # Frontend React
│   ├── services/
│   │   ├── backendApi.ts   # API backend
│   │   ├── openai.ts       # Fallback local
│   │   └── ruleNer.ts      # Règles NER
│   └── store/
│       └── documentSlice.ts # Redux avec backend
└── test-files/             # Fichiers de test

🔄 Flux de Données

graph TD
    A[Frontend React] --> B[Backend Express]
    B --> C[Tesseract.js OCR]
    B --> D[Règles NER]
    C --> E[Texte extrait]
    D --> F[Entités extraites]
    E --> G[JSON Response]
    F --> G
    G --> A

Backend (Express.js)

🚀 Serveur Principal

Fichier: backend/server.js

Port: 3001

Endpoints:

• POST /api/extract - Extraction de documents
• GET /api/test-files - Liste des fichiers de test
• GET /api/health - Health check

📄 Traitement des Documents

1. Upload et Validation

// Configuration multer
const upload = multer({
  storage: multer.diskStorage({...}),
  limits: { fileSize: 10 * 1024 * 1024 }, // 10MB max
  fileFilter: (req, file, cb) => {
    const allowedTypes = ['image/jpeg', 'image/png', 'image/tiff', 'application/pdf']
    // Validation des types de fichiers
  }
})

2. Extraction OCR Optimisée

async function extractTextFromImage(imagePath) {
  const worker = await createWorker('fra+eng')

  // Configuration optimisée pour cartes d'identité
  const params = {
    tessedit_pageseg_mode: '6',
    tessedit_char_whitelist: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ...',
    tessedit_ocr_engine_mode: '1', // LSTM
    textord_min_xheight: '6', // Petits textes
    // ... autres paramètres
  }

  await worker.setParameters(params)
  const { data } = await worker.recognize(imagePath)
  return { text: data.text, confidence: data.confidence }
}

3. Extraction NER par Règles

function extractEntitiesFromText(text) {
  const entities = {
    identities: [],
    addresses: [],
    cniNumbers: [],
    dates: [],
    documentType: 'Document',
  }

  // Patterns pour cartes d'identité
  const namePatterns = [
    /(Vendeur|Acheteur|...)\s*:\s*([A-Z][a-zà-öø-ÿ'\-]+\s+[A-Z][a-zà-öø-ÿ'\-]+)/gi,
    /^([A-Z][A-ZÀ-ÖØ-öø-ÿ\s\-']{2,30})$/gm,
    // ... autres patterns
  ]

  // Extraction des entités...
  return entities
}

📊 Réponse JSON

{
  "success": true,
  "documentId": "doc-1234567890",
  "fileName": "IMG_20250902_162159.jpg",
  "fileSize": 1077961,
  "mimeType": "image/jpeg",
  "processing": {
    "ocr": {
      "text": "Texte extrait par OCR...",
      "confidence": 85.5,
      "wordCount": 25
    },
    "ner": {
      "identities": [...],
      "addresses": [...],
      "cniNumbers": [...],
      "dates": [...],
      "documentType": "CNI"
    },
    "globalConfidence": 87.2
  },
  "extractedData": {
    "documentType": "CNI",
    "identities": [...],
    "addresses": [...],
    "cniNumbers": [...],
    "dates": [...]
  },
  "timestamp": "2025-09-15T23:30:00.000Z"
}

Frontend (React)

🔌 Service Backend

Fichier: src/services/backendApi.ts

export async function extractDocumentBackend(
  documentId: string,
  file?: File,
  hooks?: {
    onOcrProgress?: (progress: number) => void
    onLlmProgress?: (progress: number) => void
  },
): Promise<ExtractionResult> {
  const formData = new FormData()
  formData.append('document', file)

  const response = await fetch(`${BACKEND_URL}/api/extract`, {
    method: 'POST',
    body: formData,
  })

  const result: BackendExtractionResult = await response.json()

  // Conversion vers le format frontend
  return convertBackendToFrontend(result)
}

🔄 Redux Store

Fichier: src/store/documentSlice.ts

export const extractDocument = createAsyncThunk(
  'document/extract',
  async (documentId: string, thunkAPI) => {
    // Vérifier si le backend est disponible
    const backendAvailable = await checkBackendHealth()

    if (backendAvailable) {
      // Utiliser le backend
      return await backendDocumentApi.extract(documentId, file, progressHooks)
    } else {
      // Fallback vers le mode local
      return await openaiDocumentApi.extract(documentId, file, progressHooks)
    }
  },
)

Démarrage

🚀 Backend

# Option 1: Script automatique
./start-backend.sh

# Option 2: Manuel
cd backend
npm install
node server.js

🌐 Frontend

npm run dev

🧪 Test de l'Architecture

node test-backend-architecture.cjs

Avantages

🚀 Performance

• Traitement centralisé : OCR et NER sur le serveur
• Optimisations : Paramètres OCR optimisés pour les cartes d'identité
• Cache : Possibilité de mettre en cache les résultats

🔧 Maintenabilité

• Séparation des responsabilités : Backend pour le traitement, frontend pour l'UI
• API REST : Interface claire entre frontend et backend
• Fallback : Mode local en cas d'indisponibilité du backend

📊 Monitoring

• Logs détaillés : Traçabilité complète du traitement
• Health check : Vérification de l'état du backend
• Métriques : Confiance OCR, nombre d'entités extraites

Configuration

🔧 Variables d'Environnement

Backend:

• PORT=3001 - Port du serveur backend

Frontend:

• VITE_BACKEND_URL=http://localhost:3001 - URL du backend
• VITE_USE_RULE_NER=true - Mode règles locales (fallback)
• VITE_DISABLE_LLM=true - Désactiver LLM

📁 Structure des Fichiers

backend/
├── server.js              # Serveur Express
├── package.json           # Dépendances
└── uploads/               # Fichiers temporaires (auto-créé)

src/services/
├── backendApi.ts          # API backend
├── openai.ts              # Fallback local
└── ruleNer.ts             # Règles NER

docs/
└── architecture-backend.md # Cette documentation

Dépannage

❌ Problèmes Courants

Backend non accessible

# Vérifier que le backend est démarré
curl http://localhost:3001/api/health

# Vérifier les logs
cd backend && node server.js

Erreurs OCR

• Vérifier la taille des images (minimum 3x3 pixels)
• Ajuster les paramètres textord_min_xheight
• Vérifier les types de fichiers supportés

Erreurs de communication

• Vérifier que les ports 3001 (backend) et 5176 (frontend) sont libres
• Vérifier la configuration CORS
• Vérifier les variables d'environnement

🔍 Logs

Backend:

🚀 Serveur backend démarré sur le port 3001
📡 API disponible sur: http://localhost:3001/api
[OCR] Début de l'extraction pour: uploads/document-123.jpg
[OCR] Extraction terminée - Confiance: 85.5%
[NER] Extraction terminée: 2 identités, 1 adresse, 1 CNI

Frontend:

🚀 [STORE] Utilisation du backend pour l'extraction
📊 [PROGRESS] OCR doc-123: 30%
📊 [PROGRESS] NER doc-123: 50%
🎉 [BACKEND] Extraction terminée avec succès

Évolutions Futures

🔮 Améliorations Possibles

1. Base de données : Stockage des résultats d'extraction
2. Cache Redis : Mise en cache des résultats OCR
3. Queue système : Traitement asynchrone des gros volumes
4. API GraphQL : Interface plus flexible
5. Microservices : Séparation OCR et NER
6. Docker : Containerisation pour le déploiement
7. Monitoring : Métriques et alertes
8. Tests automatisés : Suite de tests complète