4nk/4NK_IA_back
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_IA_back/docs/ARCHITECTURE.md
ncantu 5cb4f1708b docs: Ajout de la documentation complète du système 
- 📚 NETWORK.md : Architecture réseau et communication inter-services
- 🏗️ ARCHITECTURE.md : Architecture technique et flux de données
- ⚙️ CONFIGURATION.md : Configuration complète des services
- 🚀 INSTALLATION.md : Guide d'installation détaillé

Documentation exhaustive couvrant :
- Topologie réseau et ports
- Architecture microservices
- Configuration Docker et services
- Guide d'installation pas à pas
- Dépannage et monitoring
- Checklist de déploiement
2025-09-09 06:25:31 +02:00

466 lines
15 KiB
Markdown
Raw Blame History

# Architecture du Système - 4NK_IA Notarial
## 🏗️ Vue d'ensemble de l'Architecture
Le système notarial 4NK_IA est conçu selon une architecture microservices moderne, utilisant des conteneurs Docker pour la scalabilité et la maintenabilité.
## 🎯 Principes Architecturaux
### **1. Séparation des Responsabilités**
- **API** : Gestion des requêtes et orchestration
- **Worker** : Traitement asynchrone des documents
- **Storage** : Persistance des données
- **UI** : Interface utilisateur
### **2. Scalabilité Horizontale**
- Services conteneurisés
- Load balancing avec Traefik
- Queue de traitement avec Celery
- Base de données distribuée
### **3. Résilience et Fiabilité**
- Health checks automatiques
- Retry policies
- Circuit breakers
- Monitoring complet
## 🏛️ Architecture Logique
```
┌─────────────────────────────────────────────────────────────────┐
│ COUCHE PRÉSENTATION │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Client │ │ Notaire │ │ Admin │ │
│ │ Web │ │ Mobile │ │ Dashboard │ │
│ │ (React) │ │ (API) │ │ (Grafana) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
│ HTTP/HTTPS
┌─────────────────────▼───────────────────────────────────────────┐
│ COUCHE API GATEWAY │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ TRAEFIK │ │
│ │ Load Balancer + SSL │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ COUCHE SERVICES │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ API │ │ Worker │ │ Web UI │ │
│ │ FastAPI │ │ Celery │ │ Static │ │
│ │ (8000) │ │ (Async) │ │ (8081) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ COUCHE TRAITEMENT │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Preprocess │ │ OCR │ │ Classify │ │
│ │ Pipeline │ │ Pipeline │ │ Pipeline │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Extract │ │ Index │ │ Checks │ │
│ │ Pipeline │ │ Pipeline │ │ Pipeline │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────────────────┐
│ COUCHE DONNÉES │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ MinIO │ │
│ │ (Structured)│ │ (Cache) │ │ (Objects) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Neo4j │ │ OpenSearch │ │ AnythingLLM │ │
│ │ (Graph) │ │ (Search) │ │ (RAG) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 🔄 Flux de Données
### **1. Upload et Traitement de Document**
```mermaid
sequenceDiagram
participant C as Client
participant A as API
participant W as Worker
participant DB as Database
participant S as Storage
participant LLM as Ollama
C->>A: POST /upload
A->>DB: Save document metadata
A->>W: Queue processing task
A->>C: Return document ID
W->>S: Download document
W->>W: Preprocess
W->>W: OCR extraction
W->>LLM: Classify document
W->>W: Extract entities
W->>W: Run verifications
W->>DB: Save results
W->>A: Update status
```
### **2. Pipeline de Traitement**
```python
# Orchestration des pipelines
def process_document(doc_id: str):
ctx = {"doc_id": doc_id}
# 1. Pré-traitement
preprocess.run(doc_id, ctx)
# 2. OCR
ocr.run(doc_id, ctx)
# 3. Classification
classify.run(doc_id, ctx)
# 4. Extraction d'entités
extract.run(doc_id, ctx)
# 5. Indexation
index.run(doc_id, ctx)
# 6. Vérifications
checks.run(doc_id, ctx)
# 7. Finalisation
finalize.run(doc_id, ctx)
```
## 🗄️ Architecture des Données
### **Modèle de Données Principal**
```sql
-- Documents
CREATE TABLE documents (
id UUID PRIMARY KEY,
filename VARCHAR(255) NOT NULL,
status VARCHAR(50) DEFAULT 'uploaded',
document_type VARCHAR(100),
ocr_text TEXT,
confidence_score FLOAT,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Entités extraites
CREATE TABLE entities (
id UUID PRIMARY KEY,
document_id UUID REFERENCES documents(id),
entity_type VARCHAR(50) NOT NULL,
entity_value TEXT NOT NULL,
confidence FLOAT,
context TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
-- Vérifications
CREATE TABLE verifications (
id UUID PRIMARY KEY,
document_id UUID REFERENCES documents(id),
verification_type VARCHAR(100) NOT NULL,
verification_status VARCHAR(50) NOT NULL,
result_data JSONB,
created_at TIMESTAMP DEFAULT NOW()
);
```
### **Stockage Multi-Modal**
| Type de Donnée | Service | Usage |
|----------------|---------|-------|
| **Métadonnées** | PostgreSQL | Données structurées |
| **Documents** | MinIO | Fichiers originaux |
| **Cache** | Redis | Sessions et cache |
| **Graphe** | Neo4j | Relations entre entités |
| **Recherche** | OpenSearch | Indexation full-text |
| **RAG** | AnythingLLM | Contexte LLM |
## 🔧 Composants Techniques
### **1. API FastAPI**
```python
# Structure de l'API
app = FastAPI(
title="API Notariale",
version="1.0.0",
description="API pour l'analyse de documents notariaux"
)
# Routes principales
@app.post("/api/notary/upload")
async def upload_document(file: UploadFile):
# Upload et traitement
pass
@app.get("/api/notary/documents/{doc_id}")
async def get_document(doc_id: str):
# Récupération des résultats
pass
```
### **2. Worker Celery**
```python
# Configuration Celery
app = Celery('worker', broker='redis://redis:6379')
@app.task
def process_document(doc_id: str, metadata: dict):
# Orchestration des pipelines
pass
```
### **3. Pipelines de Traitement**
```python
# Pipeline OCR
def run(doc_id: str, ctx: dict):
# Extraction de texte avec Tesseract
# Correction lexicale notariale
# Sauvegarde des résultats
pass
```
## 🌐 Architecture de Déploiement
### **Environnement de Développement**
```yaml
# docker-compose.dev.yml
version: '3.8'
services:
api:
build: ./services/host_api
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://notariat:notariat_pwd@postgres:5432/notariat
depends_on:
- postgres
- redis
```
### **Environnement de Production**
```yaml
# docker-compose.yml
version: '3.8'
services:
traefik:
image: traefik:v3.0
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./letsencrypt:/letsencrypt
```
## 📊 Monitoring et Observabilité
### **Métriques Collectées**
```python
# Métriques API
- http_requests_total
- http_request_duration_seconds
- active_connections
- error_rate
# Métriques Worker
- tasks_completed_total
- tasks_failed_total
- task_duration_seconds
- queue_length
# Métriques Base de Données
- db_connections_active
- db_queries_per_second
- db_query_duration_seconds
```
### **Logs Structurés**
```python
# Format des logs
{
"timestamp": "2025-09-09T04:58:07Z",
"level": "INFO",
"service": "api",
"request_id": "req_123",
"user_id": "user_456",
"message": "Document processed successfully",
"metadata": {
"doc_id": "doc_789",
"processing_time": 2.5,
"document_type": "acte_vente"
}
}
```
## 🔒 Sécurité
### **Authentification et Autorisation**
```python
# JWT Authentication
from fastapi_jwt_auth import AuthJWT
@AuthJWT.verify_token
def verify_token(token: str):
# Vérification du token JWT
pass
# RBAC (Role-Based Access Control)
ROLES = {
"notaire": ["read", "write", "process"],
"clerk": ["read", "write"],
"admin": ["read", "write", "process", "admin"]
}
```
### **Chiffrement des Données**
```python
# Chiffrement des données sensibles
from cryptography.fernet import Fernet
def encrypt_sensitive_data(data: str) -> str:
# Chiffrement AES-256
pass
def decrypt_sensitive_data(encrypted_data: str) -> str:
# Déchiffrement
pass
```
## 🚀 Scalabilité
### **Scaling Horizontal**
```yaml
# Docker Swarm / Kubernetes
api:
replicas: 3
resources:
limits:
memory: "512Mi"
cpu: "500m"
requests:
memory: "256Mi"
cpu: "250m"
worker:
replicas: 5
resources:
limits:
memory: "1Gi"
cpu: "1000m"
```
### **Cache Strategy**
```python
# Redis Cache Layers
CACHE_LAYERS = {
"L1": "In-memory (FastAPI)",
"L2": "Redis (Distributed)",
"L3": "Database (Persistent)"
}
# Cache TTL
CACHE_TTL = {
"document_analysis": 3600, # 1 heure
"user_sessions": 86400, # 24 heures
"api_responses": 300 # 5 minutes
}
```
## 🔄 CI/CD Pipeline
### **Pipeline de Déploiement**
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run tests
run: pytest tests/
build:
needs: test
runs-on: ubuntu-latest
steps:
- name: Build Docker images
run: docker build -t api:latest ./services/host_api
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: docker-compose up -d
```
## 📋 Checklist Architecture
### **Design Patterns Implémentés**
- [x] **Repository Pattern** : Abstraction de la couche données
- [x] **Factory Pattern** : Création des pipelines
- [x] **Observer Pattern** : Événements de traitement
- [x] **Strategy Pattern** : Différents types de classification
- [x] **Circuit Breaker** : Gestion des pannes
- [x] **Retry Pattern** : Gestion des erreurs temporaires
### **Qualités Non-Fonctionnelles**
- [x] **Performance** : < 2s pour l'upload, < 30s pour le traitement
- [x] **Disponibilité** : 99.9% uptime
- [x] **Scalabilité** : Support 1000+ documents/jour
- [x] **Sécurité** : Chiffrement, authentification, audit
- [x] **Maintenabilité** : Code modulaire, tests, documentation
- [x] **Observabilité** : Logs, métriques, traces
## 🎯 Évolutions Futures
### **Roadmap Technique**
1. **Q1 2025** : Migration vers Kubernetes
2. **Q2 2025** : Intégration IA avancée (GPT-4)
3. **Q3 2025** : API GraphQL
4. **Q4 2025** : Multi-tenant architecture
### **Optimisations Prévues**
- **Edge Computing** : Traitement local
- **Streaming** : Traitement en temps réel
- **MLOps** : Pipeline d'entraînement automatique
- **Blockchain** : Traçabilité des documents
Reference in New Issue View Git Blame Copy Permalink