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

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

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

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

ExtractionResult

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

AnalysisResult

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