4NK_IA_front/docs/ARCHITECTURE.md

# Architecture de l'application 4NK IA Front Notarial

## Vue d'ensemble

L'application 4NK IA Front Notarial est une interface web moderne construite avec React et TypeScript,
conçue pour l'analyse intelligente de documents notariaux.

## Stack technique

### Frontend

- **React 18** : Framework UI avec hooks et composants fonctionnels
- **TypeScript 5.6** : Typage statique pour la robustesse du code
- **Vite 7** : Build tool rapide avec HMR (Hot Module Replacement)
- **Material-UI v6** : Bibliothèque de composants UI professionnels

### Gestion d'état

- **Redux Toolkit** : Gestion d'état centralisée et prévisible
- **React Redux** : Liaison React-Redux avec hooks
- **Async Thunks** : Gestion des actions asynchrones

### Routing et navigation

- **React Router v6** : Navigation côté client avec code splitting
- **Lazy loading** : Chargement à la demande des composants

### HTTP et API

- **Axios** : Client HTTP avec intercepteurs
- **Intercepteurs** : Gestion centralisée des erreurs et authentification

### Tests

- **Vitest** : Framework de test rapide et moderne
- **Testing Library** : Tests d'intégration React
- **JSDOM** : Environnement DOM simulé
- **Coverage V8** : Rapport de couverture de code

### Qualité de code

- **ESLint** : Linting avec règles strictes
- **Prettier** : Formatage automatique du code
- **markdownlint** : Validation des fichiers Markdown

## Structure du projet

```text
src/
├── components/          # Composants réutilisables
│   ├── Layout.tsx      # Layout principal avec AppBar et navigation
│   └── NavigationTabs.tsx # Composant de navigation par onglets
├── views/              # Vues principales de l'application
│   ├── UploadView.tsx  # Upload et gestion des documents
│   ├── ExtractionView.tsx # Affichage des données extraites
│   ├── AnalyseView.tsx # Analyse et score de vraisemblance
│   ├── ContexteView.tsx # Données contextuelles externes
│   └── ConseilView.tsx # Conseil IA et recommandations
├── store/              # Gestion d'état Redux
│   ├── index.ts        # Configuration du store Redux
│   ├── appSlice.ts     # État global de l'application
│   └── documentSlice.ts # État des documents et opérations
├── services/           # Services et API
│   └── api.ts          # Client API et endpoints
├── types/              # Types et interfaces TypeScript
│   └── index.ts        # Définitions de types centralisées
├── main.tsx           # Point d'entrée de l'application
└── App.tsx            # Composant racine avec routing
```

## Architecture des composants

### Layout et navigation

- **Layout** : Composant wrapper avec AppBar et navigation
- **NavigationTabs** : Navigation par onglets avec React Router
- **AppBar** : Barre de navigation principale

### Vues principales

#### UploadView

- **Dropzone** : Zone de glisser-déposer pour les fichiers
- **FileList** : Liste des documents uploadés
- **Status indicators** : Indicateurs de statut des documents

#### ExtractionView

- **DataDisplay** : Affichage des données extraites
- **ObjectLists** : Listes d'identités, adresses, biens, contrats
- **Confidence scores** : Scores de confiance des extractions

#### AnalyseView

- **CredibilityScore** : Score de vraisemblance du document
- **Recommendations** : Liste des recommandations
- **Summary** : Synthèse de l'analyse

#### ContexteView

- **ExternalData** : Données des APIs externes
- **StatusCards** : Cartes de statut pour chaque source
- **LastUpdated** : Horodatage des dernières mises à jour

#### ConseilView

- **LLMAnalysis** : Analyse générée par l'IA
- **RiskAssessment** : Évaluation des risques
- **NextSteps** : Prochaines étapes recommandées

## Gestion d'état Redux

### Structure du store

```typescript
interface RootState {
  app: AppState        // État global de l'application
  document: DocumentState // État des documents et opérations
}
```

### AppState

- **status** : État global ('idle' | 'loading' | 'succeeded' | 'failed')
- **error** : Messages d'erreur globaux

### DocumentState

- **documents** : Liste des documents uploadés
- **currentDocument** : Document actuellement sélectionné
- **extractionResult** : Résultats d'extraction
- **analysisResult** : Résultats d'analyse
- **contextResult** : Données contextuelles
- **conseilResult** : Conseil IA
- **loading** : État de chargement
- **error** : Messages d'erreur

### Actions asynchrones

- **uploadDocument** : Upload d'un document
- **extractDocument** : Extraction des données
- **analyzeDocument** : Analyse du document
- **getContextData** : Récupération des données contextuelles
- **getConseil** : Génération du conseil IA

## Services API

### Configuration Axios

- **Base URL** : Configuration via variables d'environnement
- **Timeout** : 60 secondes pour les opérations longues
- **Intercepteurs** : Gestion d'erreur et fallback automatique

### Endpoints

- `POST /api/documents/upload` : Upload de document
- `GET /api/documents/{id}/extract` : Extraction de données
- `GET /api/documents/{id}/analyze` : Analyse du document
- `GET /api/documents/{id}/context` : Données contextuelles
- `GET /api/documents/{id}/conseil` : Conseil IA

### Gestion d'erreur

- **Intercepteurs** : Détection automatique des erreurs
- **Fallback** : Données de démonstration en cas d'erreur
- **Codes gérés** : 404, 405, ERR_NETWORK, ERR_CONNECTION_REFUSED

## Types et interfaces

### Document

```typescript
interface Document {
  id: string
  name: string
  type: string
  size: number
  uploadDate: Date
  status: 'uploading' | 'processing' | 'completed' | 'error'
}
```

### ExtractionResult

```typescript
interface ExtractionResult {
  documentId: string
  text: string
  language: string
  documentType: string
  identities: Identity[]
  addresses: Address[]
  properties: Property[]
  contracts: Contract[]
  signatures: string[]
  confidence: number
}
```

### AnalysisResult

```typescript
interface AnalysisResult {
  documentId: string
  documentType: string
  isCNI: boolean
  credibilityScore: number
  summary: string
  recommendations: string[]
}
```

## Mode démonstration

### Fonctionnement

- **Détection automatique** : Vérification de la disponibilité du backend
- **Fallback gracieux** : Basculement vers des données de démonstration
- **Données réalistes** : Exemples d'actes notariaux authentiques
- **Fonctionnalités complètes** : Toutes les vues opérationnelles

### Données de démonstration

- **Documents** : Exemples d'actes de vente, CNI, etc.
- **Identités** : Personnes avec informations complètes
- **Adresses** : Adresses françaises réalistes
- **Biens** : Propriétés avec références cadastrales
- **Contrats** : Clauses et montants réalistes

## Performance et optimisation

### Code splitting

- **Lazy loading** : Chargement à la demande des vues
- **Suspense** : Gestion des états de chargement
- **Bundle optimization** : Optimisation de la taille des bundles

### Caching

- **Redux state** : Mise en cache des données dans le store
- **API responses** : Cache des réponses API
- **Component memoization** : Optimisation des re-renders

### Build optimization

- **Vite** : Build rapide avec optimisations automatiques
- **Tree shaking** : Élimination du code mort
- **Minification** : Compression du code de production

## Sécurité

### Validation

- **TypeScript** : Validation de types à la compilation
- **Runtime validation** : Validation des données API
- **Input sanitization** : Nettoyage des entrées utilisateur

### CORS et CSP

- **CORS** : Configuration des en-têtes Cross-Origin
- **CSP** : Content Security Policy pour la sécurité
- **HTTPS** : Communication sécurisée en production

## Déploiement

### Environnements

- **Développement** : Serveur local avec HMR
- **Staging** : Environnement de test
- **Production** : Déploiement optimisé

### Variables d'environnement

- **VITE_API_URL** : URL de l'API backend
- **VITE_*_API_URL** : URLs des APIs externes
- **NODE_ENV** : Environnement d'exécution

### Build de production

- **Optimisation** : Minification et compression
- **Assets** : Optimisation des images et CSS
- **Bundle analysis** : Analyse de la taille des bundles