LeadFlow — Document d'architecture

📄 Pour un PDF : ouvre ce fichier dans Chrome → Ctrl + P → « Enregistrer au format PDF » → coche « Graphiques d'arrière-plan ».

Vue d'ensemble & objectif

Ce qu'on construit et le principe directeur

Objectif

Un portail SaaS qui automatise la gestion des leads pour des centaines d'agences immobilières.
4 briques : capture multi-portails · réponse automatique <60 s · qualification par chatbot/IA · relances automatiques.
Déployable selon ce que veut l'agence : chez toi (SaaS), en instance dédiée, ou chez elle (auto-hébergé).

Le principe directeur

Un seul code, plusieurs modes de déploiement. On code l'application une seule fois, mais conçue dès le départ pour tourner soit sur ton serveur, soit sur celui de l'agence — sans réécriture. Rendu possible par : conteneurisation (Docker), couche d'IA abstraite, et configuration par environnement.

La confidentialité = argument de vente

Au lieu de subir le « on ne veut pas externaliser nos données », on le retourne en « choisissez où vivent vos données » — le même levier qui fait gagner des contrats pour ComplyFlow (Nextcloud auto-hébergé).

Le moteur : qui fait quoi

Clarification essentielle pour ne pas se tromper d'architecture

Brique	C'est quoi	Son rôle
Claude Code	Outil de développement (assistant de code)	Construit le logiciel. Ne tourne jamais en production.
Le backend	Vraie appli serveur (Python/FastAPI) qui tourne 24/7	LE moteur : encaisse les leads, orchestre tout, gère les agences.
L'API d'IA	Le « cerveau » (Claude / Gemini), appelé par du code	Appelé par le backend uniquement pour les tâches d'IA (qualifier, rédiger).

On ne fait pas tourner Claude Code en production. Le moteur live, c'est ton backend déployé sur ton serveur, qui appelle l'API quand il faut « réfléchir ». De même, on ne « pose » pas le modèle Claude sur un serveur (pas open-source → accès API uniquement). Pour du 100 % local, on utilise un modèle open-source (Llama/Mistral) — voir §5.

Architecture fonctionnelle

Le parcours d'un lead, brique par brique

Lead (Rightmove · Zoopla · site · Facebook) │ 1. CAPTURE → parsing email / webhook / API → normalisé dans la base │ 2. RÉPONSE <60s → SMS + email + WhatsApp instantanés (Twilio) │ 3. QUALIFICATION → chatbot : budget · zone · délai · financement → score 🔥/🟠/❄️ │ (appel API IA) → routage négociateur │ 4. RELANCES → séquence J+1/J+3/J+7… jusqu'à conversion ou opt-out

1 · Capture multi-portails

Parsing d'email : les leads Rightmove/Zoopla arrivent par email → lus en IMAP, champs extraits (nom, tél, bien).
Webhooks : formulaire du site, Facebook Lead Ads.
API/feed portail si l'agence y a accès. Tout est normalisé dans un format unique.

2 · Réponse automatique <60 s

Dès réception → message personnalisé (SMS/email/WhatsApp) avec lien de réservation de visite. La vitesse = facteur n°1 de conversion.

3 · Qualification par chatbot

4-5 questions (budget, zone, délai, cash/prêt) → scoring → chaud = négociateur alerté ; froid = séquence de relance.
Sans IA (arbre fixe) ou avec IA (conversation naturelle).

4 · Relances automatiques

Séquence programmée sur 30-90 j, stoppée automatiquement dès réponse / visite / désinscription.

Les 3 modes de déploiement

Même code — l'agence choisit où vivent ses données

A · SaaS mutualisé

Tu héberges (en UE). Toutes les agences partagent l'infra, données isolées par agence.

Le moins cher · onboarding instantané

B · Instance dédiée

Un déploiement isolé par agence (sa propre base / conteneur), chez toi ou dans son cloud.

Intermédiaire

C · Auto-hébergé

Installé sur le serveur de l'agence. Les données ne sortent jamais de chez elle.

Premium · zéro externalisation

Mode	Où sont les données	Pour qui
A · Mutualisé	Ton serveur (UE), isolées par `agency_id`	La majorité des agences
B · Dédié	Serveur dédié (tien ou à elles)	Agences moyennes prudentes
C · Auto-hébergé	Leur propre serveur	Grosses agences / refus d'externaliser

Comme c'est le même conteneur Docker, passer de A à C = un déploiement différent, pas un autre logiciel. Tu ne maintiens qu'une seule base de code.

Stratégie IA & données (RGPD)

Le vrai sujet : que devient la donnée quand on appelle l'IA ?

Même en auto-hébergé, si on appelle une API d'IA, le texte sort vers le fournisseur. Trois réponses, du plus simple au plus strict :

Option 1 · API en UE + DPA + non-entraînement (défaut recommandé)

Gemini Vertex région UE (ou Anthropic sous contrat) : données traitées en Europe, non utilisées pour l'entraînement, supprimées vite, sous contrat de sous-traitance (DPA). Conforme RGPD pour l'immense majorité.

Option 2 · Minimisation des données (à faire systématiquement)

On n'envoie à l'IA que le nécessaire (ex. le message du lead), pseudonymisé (pas de nom/téléphone). Le reste reste dans la base.

Option 3 · Modèle open-source auto-hébergé (pour les irréductibles)

Llama / Mistral tournant sur le serveur de l'agence (GPU) : zéro donnée sortante. Qualité un peu en dessous, plus de maintenance.

Clé technique : une couche ai_provider abstraite permet de basculer Claude ↔ Gemini ↔ modèle local par un simple réglage, par agence. La portabilité est dans le code dès le jour 1.

Stack technique

Les briques concrètes

Couche	Choix	Pourquoi
Backend	Python · FastAPI	Rapide, async, propre ; tu codes déjà en Python
Base de données	PostgreSQL	Robuste, multi-tenant, relationnel
File / planif.	Redis + worker (RQ/Celery)	Séquences de relance, tâches asynchrones
Portail (front)	React (ou server-rendered au début)	Login agence, dashboard, config
IA	Couche `ai_provider` : Claude / Gemini UE / local	Portabilité & RGPD
Intégrations	Twilio · WhatsApp Business · IMAP · Brevo/SendGrid	SMS, WhatsApp, parsing email, envois
Déploiement	Docker + Nginx + TLS	Même conteneur partout (modes A/B/C)

[ Nginx + TLS ] │ [ FastAPI ] ──appelle──> ai_provider (Claude / Gemini / local) │ │ │ Postgres Redis Intégrations (Twilio · WhatsApp · IMAP · email) │ [ React ] portail agences

Modèle de données multi-tenant

Comment isoler proprement des centaines d'agences

Chaque table « métier » porte un agency_id → isolation stricte par agence (une agence ne voit jamais les données d'une autre). En mode dédié/auto-hébergé, c'est carrément une base par agence.

Table	Champs clés
agencies	id, nom, mode (A/B/C), config_portails, twilio_cfg, ai_provider, branding
users	id, agency_id, email, rôle (admin/négociateur), hash_mdp
leads	id, agency_id, source (rightmove…), nom, tél, email, bien, statut, score, négociateur_id, created_at
conversations	id, lead_id, canal (sms/wa/email), état
messages	id, conversation_id, sens (in/out), contenu, ts
sequences	id, agency_id, étapes (J+1/J+3…), conditions d'arrêt
tasks (file)	id, lead_id, type (relance), exécuter_le, état
audit_log	id, agency_id, user_id, action, ts (traçabilité RGPD)

Scoring & qualification stockés sur le lead → le dashboard filtre instantanément les « 🔥 chauds » à rappeler.

Sécurité & conformité

Indispensable sur des données personnelles (RGPD)

Sécurité technique

Chiffrement en transit (TLS) et au repos (DB chiffrée).
Auth par agence : comptes, rôles, jetons (JWT), mots de passe hachés (bcrypt/argon2).
Isolation stricte par agency_id (et tests anti-fuite inter-agences).
Secrets (clés API, Twilio) hors du code, en variables d'environnement / coffre.

Conformité RGPD

Minimisation + pseudonymisation avant tout appel IA (§5).
Base légale : intérêt légitime / consentement pour les relances (opt-out clair dans chaque message).
Droits : effacement, export, conservation limitée (purge auto des leads inactifs).
Sous-traitance : DPA avec le fournisseur d'IA + registre des traitements.
Journal d'audit : qui a accédé à quoi, quand.

Feuille de route (build)

Par étapes, chaque étape livre quelque chose de testable

Socle — FastAPI conteneurisé : endpoint de capture de lead → stockage Postgres → réponse auto (simulée) → mini-API. Couche ai_provider abstraite posée d'entrée.

Qualification — chatbot + scoring via l'API IA ; routage vers le négociateur.

Relances — file Redis + worker : séquences J+1/J+3…, conditions d'arrêt, opt-out.

Portail web multi-agences — auth, rôles, dashboard leads, config par agence.

Intégrations réelles & déploiement — Twilio/WhatsApp, parsing emails portails, Docker prod (modes A/B/C), TLS.

On peut démarrer l'étape 1 tout de suite, en local sur ton PC, et avancer brique par brique.

Coûts & montée en charge

Tenir des centaines d'agences

Montée en charge

Backend stateless → on lance plusieurs instances derrière Nginx ; la DB et la file encaissent la charge.
Multi-tenant = une seule infra sert toutes les agences (mode A) → coût marginal faible par agence.

Postes de coût

Poste	Ordre de grandeur
Serveur (VPS)	~5–40 €/mois selon charge (Scaleway/OVH/Hetzner)
IA (API)	Quelques centimes par lead qualifié ; monte avec le volume
SMS/WhatsApp (Twilio)	À l'usage, ~0,03–0,08 € / SMS
Email (Brevo/SendGrid)	Gratuit→faible jusqu'à gros volumes

Modèle économique : abonnement mensuel par agence (retainer) — le coût d'infra/IA est largement couvert, surtout en mutualisé.