Imago/docs/ARCHITECTURE.md

Architecture Technique - Imago Hub

Ce document détaille l'architecture logicielle, les flux de données et les choix technologiques d'Imago Hub. Il s'adresse aux développeurs, architectes et contributeurs du projet.

---

🏗️ 1. Vue d'Ensemble des Composants

Imago s'articule autour de plusieurs services distincts orchestrés via Docker, communiquant par des interfaces asynchrones et résilientes.

La Stack Technique

• Backend API Layer : FastAPI (Python 3.10+) pour des performances maximales, des endpoints asynchrones (async/await) et une validation native (Pydantic). L'API répond vite, elle ne bloque jamais sur l'IO réseau.
• Frontend Admin : React (JavaScript/TypeScript) propulsé par Vite et servi via Nginx. Interface Single-Page minimaliste, rapide.
• Worker Queue : ARQ (Async Redis Queue). Une alternative moderne s'appuyant sur l'Event Loop natif d'asyncio Python au lieu de frameworks lourds.
• Broker & Cache : Redis stocke les jobs temporaires, limite les taux (Rate Limiting) et gère le pub/sub des requêtes websocket.
• Base de données : PostgreSQL interrogé via SQLAlchemy (orm asynchrone : asyncpg).
• Objets & Médias : MinIO implémentant le standard S3 (ou un volume filesystem classique) pour isoler les données binaires massives.

---

🔄 2. Flux de Traitement Asynchrone (Le Pipeline)

Toute la valeur d'Imago réside dans sa capacité à dépiler un flux lourd d'images de façon déconnectée des appels HTTP des utilisateurs finaux.

Chronologie d'un événement Upload

1. Le client effectue un POST /upload. L'API FastAPI, en streaming mémoire, pousse l'image vers le backend de stockage (S3).
2. L'API enregistre dans PostgreSQL l'image avec un statut PENDING.
3. L'API publie un message enqueue vers ARQ/Redis : analyse_image(db_id=124).
4. L'API répond immédiatement au client HTTP avec 202 Accepted et l'UUID généré.

Boucle du Worker ARQ (processus séparé)

Une fois le message attrapé par le démon worker.py :

1. Verrouillage : Le statut passe à PROCESSING.
2. Étape EXIF : (via exifread / modules Python) analyse purement metadata, parse le GPS et écrit dans les tables reliées.
3. Étape OCR : Tesseract est encapsulé. Il scanne l'image et met à jour l'entité PostgreSQL.
4. Étape IA Vision : Un client HTTP asynchrone (httpx) effectue un appel API vers Google (Gemini) ou OpenRouter. Une demande de structuration en prompt pur JSON assure des typages clairs.
5. Clôture : Le statut passe à COMPLETED.

(En cas d'échec sur une étape isolée comme le réseau IA, le worker utilise la retry-policy asynchrone native d'ARQ).

---

🗄️ 3. Modèle de Données & Multi-tenancy

La BDD relationnelle s'articule pour cloisonner (isolation de locataire) les données de façon logicielle :

• Table Clients : Représente le "Tenant". Un Client possède plusieurs clés API hashées (Bcrypt) et un "plan" définissant ses quotas.
• Table Image : Clé principale. Chaque Image possède une client_id liant la ressource directement au Tenant. C'est l'essence du filtrage (Aucune requête RDBM vers Images ne démarre sans WHERE client_id = X).
• Tables Satellites (Exif, OCR, AITasks) : Héritent des dépendances (Cascade Deletes) liant l'information technique à l'uuid Image.

Le Rate Limiting Distribué

Le limiter applicatif s'appuie sur slowapi et le backend Redis. L'ID du tenant (Client Object) sert de clé dans Redis pour évaluer le bucket algorithmique :

• Permet de bloquer avant l'appel FastAPI les clients abusifs en respectant strictement l'architecture distribuée.

---

🔌 4. Observabilité et Temps Réel

• FastAPI Websockets Pub/Sub : L'API monte des sessions WebSockets bidirectionnelles. Lors d'un changement dans PostgreSQL (Via un event déclenché par ARQ en fin de boucle), un hook publie un patch JSON aux websockets écoutants. L'UI (Shaarli / Admin) est ré-invalider sans actualisation HTTP.
• Prometheus Metrics : Le endpoint /metrics expose via un middleware des données quantitatives brutes de latence et volumétries. Facilement gratté (scraped) par des tableaux Grafana ou Datadog.