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

```mermaid
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
```javascript
// 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
```javascript
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
```javascript
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

```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`

```typescript
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`

```typescript
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

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

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

### 🌐 Frontend

```bash
npm run dev
```

### 🧪 Test de l'Architecture

```bash
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
```bash
# 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