Julius

1. Présentation du projet

Julius (nom commercial) / Advanced Scraper (nom technique) est une application web full-stack conçue pour automatiser la prospection commerciale et la recherche de profils professionnels.

L'application permet aux utilisateurs de :

• Construire des requêtes de recherche avancées (Google Dorks, opérateurs booléens, filtres géographiques et par réseau social)
• Lancer des extractions automatisées pour récupérer des informations de contact (emails, téléphones, profils LinkedIn, etc.)
• S'appuyer sur un assistant IA pour générer des configurations de recherche optimisées selon leur profil métier
• Exporter les résultats aux formats CSV et XLSX
• Gérer leurs crédits, leur historique d'extractions et leur profil utilisateur

Le projet est structuré en monorepo avec un frontend React et un backend Python Flask, connectés à des services cloud (Supabase, APIs Google et OpenAI).

2. Objectifs de la solution

Problématique adressée

La prospection manuelle de leads est chronophage, répétitive et demande une maîtrise des techniques de recherche avancées (Google Dorks, ciblage LinkedIn, filtres booléens). Les équipes commerciales perdent du temps à construire des requêtes, parcourir les résultats et extraire manuellement les coordonnées.

Objectifs principaux

3. Public cible

Julius s'adresse principalement à :

• Équipes commerciales (B2B / B2C) — prospection, génération de leads qualifiés, identification de décideurs
• Recruteurs et chasseurs de têtes — recherche de profils LinkedIn selon des critères précis (poste, localisation, secteur)
• Agences marketing et growth — campagnes de prospection ciblées par pays, secteur ou réseau social
• Freelances et consultants — recherche de clients potentiels sans outils enterprise coûteux
• Administrateurs de la plateforme — gestion des utilisateurs, rôles et crédits via un espace admin

Le produit est pensé pour des utilisateurs qui ont besoin de volume et de précision dans leur prospection, tout en conservant une interface accessible aux débutants grâce à l'assistant IA.

4. Fonctionnalités

4.1 Recherche avancée

• Saisie de mots-clés avec opérateurs booléens (AND, OR, NOT)
• Filtres par type de contenu (profils, documents, etc.)
• Filtres par réseau social (LinkedIn, Twitter, etc.)
• Filtres géographiques (pays, région, ville)
• Prévisualisation de la requête Google générée avant exécution
• Historique des recherches récentes

Implémentation : SearchForm.js, SearchResults.js — API /api/search

4.2 Extraction de contacts

• Lancement d'extractions à partir des résultats de recherche
• Extraction asynchrone en arrière-plan avec suivi de progression
• Données extraites : noms, emails, téléphones, entreprises, titres, URLs de profils
• Export CSV et XLSX
• Historique des extractions avec statuts (pending, processing, completed, failed)
• Téléchargement des fichiers générés

Implémentation : pages Extractions, Exports — API /api/extraction/*

4.3 AI Search Helper

Assistant IA intégré qui :

1. Collecte le profil métier de l'utilisateur (secteur, objectif, client idéal, budget, etc.)
2. Génère 3 à 5 configurations de recherche personnalisées via OpenAI GPT-4o
3. Permet d'appliquer une suggestion en un clic sur le formulaire de recherche
4. Enregistre les suggestions appliquées pour analyse ultérieure

Implémentation : AISearchHelper.js — API /api/ai/search-helper, /api/ai/apply-suggestion

4.4 LinkedIn Extract

Fonctionnalité dédiée à la recherche et l'extraction de profils LinkedIn :

• Filtres par mots-clés, localisation, secteur, entreprise, niveau d'expérience
• Extraction structurée (expérience, formation, compétences, coordonnées)
• Rotation de proxies pour limiter les blocages
• Export CSV / XLSX

4.5 Authentification et gestion des comptes

• Inscription et connexion par email / mot de passe
• Connexion Google OAuth
• Sessions JWT gérées par Supabase Auth
• Routes protégées côté frontend (PrivateRoute) et backend (@require_auth)
• Gestion du profil utilisateur et des paramètres (thème, langue, format d'export par défaut)
• Mode invité limité en cas de restrictions de stockage navigateur

4.6 Système de crédits

• Chaque utilisateur dispose d'un solde de crédits
• Les extractions consomment des crédits selon le volume de résultats
• Historique des transactions (credit_history)
• Page dédiée à la consultation et à la gestion des crédits

4.7 Administration

• Rôles utilisateur : user et admin
• Gestion des rôles et des crédits utilisateurs
• Tableau de bord avec statistiques d'usage

4.8 Autres pages

5. Éléments techniques

5.1 Architecture globale

Flux typique :

1. L'utilisateur s'authentifie via Supabase Auth (frontend)
2. Le frontend envoie le JWT dans le header Authorization: Bearer <token>
3. Le backend valide le token et exécute la logique métier
4. Les résultats sont stockés en base Supabase et/ou exportés en fichiers
5. Le frontend affiche les résultats et permet le téléchargement

5.2 Stack frontend

Structure principale :

frontend/
├── src/
│   ├── components/     # UI, pages, navigation, auth
│   ├── contexts/       # AuthContext (session utilisateur)
│   ├── services/       # api.js, authService, supabase
│   ├── config/         # supabase.js, firebase.js (legacy)
│   └── App.js          # Routes et providers
└── public/

5.3 Stack backend

Structure principale :

backend/
├── app/
│   ├── routes/         # auth, search, extraction, ai, user, admin, export, storage, proxy
│   ├── services/       # scraper, export, supabase_auth, credit, cache
│   ├── decorators/     # require_auth, require_admin, require_credits
│   ├── middleware/     # auth_middleware, CORS
│   └── config/         # configuration et variables d'environnement
└── run.py              # Point d'entrée Flask

5.4 Base de données (Supabase / PostgreSQL)

Tables principales :

Contraintes notables : rôles (user / admin), crédits ≥ 0, statuts d'extraction contrôlés, clés étrangères vers users.

5.5 Authentification

• Service principal : Supabase Auth (JWT)
• Méthodes : email/mot de passe, Google OAuth
• Côté API : décorateur @require_auth vérifie le header Authorization: Bearer
• Côté frontend : AuthContext + PrivateRoute pour les pages protégées
• Migration en cours : traces de Firebase Auth encore présentes (config legacy, colonne firebase_uid en base)

5.6 APIs externes

5.7 Déploiement

Lancement local :

# Backend (port 8000 en dev si 5000 occupé)
cd backend && ./venv/bin/python run.py

# Frontend (port 3000)
cd frontend && npm start

Variables d'environnement requises : clés Supabase, Google API, OpenAI, etc. (voir .env et backend/.env).

5.8 Sécurité

• Authentification JWT sur toutes les routes sensibles
• Contrôle d'accès par rôles (RBAC : user / admin)
• CORS configuré avec liste blanche d'origines
• Validation des entrées côté client et serveur
• Système de crédits pour limiter les abus
• Row Level Security (RLS) côté Supabase

5.9 Points techniques remarquables

• Architecture async/sync hybride — routes Flask avec services asynchrones (OpenAI, Supabase)
• Extraction asynchrone — traitement en arrière-plan avec suivi de progression
• Compatibilité navigateur — gestion des restrictions de cookies/storage (mode restreint)
• Proxy rotation — pour les extractions LinkedIn à volume
• Monorepo — frontend et backend dans un même dépôt, scripts utilitaires à la racine