Imago/docs/ARCHITECTURE.md

Architecture Technique — Imago Hub v2.0.0

Ce document détaille l'architecture logicielle, les flux de données et les choix technologiques.

---

1. Vue d'Ensemble

Composant	Technologie	Rôle
API Backend	FastAPI (Python 3.12+) + Uvicorn	Endpoints REST async, validation Pydantic
Frontend Admin	React + TypeScript + Vite + Nginx	Interface d'administration
Worker Queue	ARQ (Async Redis Queue)	Traitement asynchrone du pipeline AI
Broker/Cache	Redis 7	Jobs ARQ, Pub/Sub WebSocket, Rate Limiting, DLQ
Base de données	PostgreSQL 16 + SQLAlchemy async	Données relationnelles, multi-tenant
Stockage objets	MinIO (S3-compatible) ou stockage local	Fichiers binaires (images, thumbnails)
Observabilité	structlog + Prometheus + Grafana	Logs structurés, métriques, dashboards

---

2. Flux de Traitement (Pipeline AI)

Client → POST /api/v1/images/upload
  → Validation MIME + quota
  → Sauvegarde fichier (S3 ou local) + thumbnail
  → Insert BDD (status: PENDING)
  → Enqueue job ARQ: process_image_task(image_id, client_id)
  → Réponse 201 au client

Worker ARQ (processus séparé):
  → status: PROCESSING
  → Étape 1: EXIF (piexif) → métadonnées appareil, GPS
  → Étape 2: OCR (Tesseract) → texte + fallback AI OCR
  → Étape 3: Vision AI (Gemini/OpenRouter) → description, tags
  → status: DONE (ou ERROR si échec après N tentatives)
  → Publication Redis Pub/Sub → WebSocket clients

Résilience :

• Chaque étape est indépendante — un échec partiel n'arrête pas le pipeline
• Circuit breaker AI : timeout configurable + retry exponentiel
• Dead Letter Queue : jobs échoués après PIPELINE_MAX_RETRIES → Redis DLQ inspectable

---

3. Modèle de Données

Table api_clients

• id (UUID), name, api_key_hash (SHA-256 + pepper)
• scopes (JSON), plan (free/standard/premium)
• storage_used_bytes, quota_storage_mb, quota_images
• is_active (soft delete)

Table images

• id, uuid, client_id → isolation multi-tenant
• original_name, file_path, thumbnail_path, mime_type, file_size
• processing_status (pending/processing/done/error)
• EXIF : exif_make, exif_model, exif_gps_lat/lon, exif_taken_at, etc.
• OCR : ocr_text, ocr_language, ocr_confidence
• AI : ai_description, ai_tags (JSON), ai_model_used, ai_prompt_tokens, ai_output_tokens
• Indexes composites : (client_id, uploaded_at), (client_id, processing_status)

---

4. Sécurité

Couche	Mécanisme
Authentification	API Key via Authorization: Bearer <key> ou X-API-Key
Hashage	SHA-256 + pepper (SECRET_KEY) — comparaison timing-safe
Master Key	ADMIN_API_KEY configurable, bypass BDD avec tous les droits
Autorisation	Scopes obligatoires par endpoint (require_scope("images:write"))
Validation	Scopes rejetés si invalides (VALID_SCOPES)
Rate Limiting	slowapi par client_id + plan, stockage Redis optionnel
CORS	Configurable, rejette ["*"] si allow_credentials=True
URLs signées	HMAC via itsdangerous (local) ou S3 presigned URLs

---

5. Observabilité

• structlog : JSON en production, console colorée en dev. Trace ID (X-Request-ID) injecté.
• Prometheus : /metrics — counters (uploads, tokens, erreurs), histograms (durée pipeline), gauges (stockage, WebSocket)
• Health checks : /health (simple), /health/detailed (BDD, Redis, ARQ, MinIO, OCR, AI, worker)
• Grafana : dashboard 10 panneaux fourni (docs/grafana-dashboard.json)

---

6. WebSocket — Temps Réel

• /ws/pipeline/{image_id}?token=API_KEY — événements live du pipeline
• /ws/admin/monitor?token=ADMIN_KEY — monitoring global admin
• Buffer Redis 60s (10 derniers événements) pour reconnexion
• Pub/Sub Redis : pipeline:{image_id} et pipeline:admin

---

7. Infrastructure & Déploiement

Développement local

docker compose up -d    # PostgreSQL + Redis + MinIO + API + Worker

Production (serveur lab)

L'image est poussée vers le registry local :

docker-registry.dev.home:5000/imago-backend:latest

Déploiement : docker-compose.production.yml + .env.production

Build & Push

cd docker
.\build-img.ps1       # Build via WSL Debian
.\deploy-img.ps1      # Push vers registry (semver auto)