ai_synth/CLAUDE.md

Documentation Technique et Fonctionnelle : AI Weekly Synth

🎯 Objectif de l'application

AI Weekly Synth est une application web permettant de générer automatiquement des synthèses d'actualités personnalisées et thématisées. Conçue pour la veille technologique ou sectorielle (par défaut centrée sur l'Intelligence Artificielle), elle utilise l'IA générative (Google Gemini) pour rechercher, filtrer, résumer et catégoriser les actualités récentes. L'application est multi-utilisateurs, garantissant à chacun un espace de veille privé et sur-mesure.

✨ Fonctionnalités offertes

• Authentification sécurisée : Connexion via compte Google (SSO) garantissant la protection des données personnelles.
• Génération de synthèses par IA : Recherche sur le web et création de résumés structurés basés sur les paramètres de l'utilisateur.
• Gestion des sources personnalisées : Possibilité d'ajouter des URLs spécifiques (blogs, sites d'actualité, flux) que l'IA doit consulter en priorité lors de la génération.
• Configuration sur-mesure (Paramètres) :
  • Choix du thème de veille (ex: "Intelligence Artificielle", "Cybersécurité", "Économie").
  • Définition de la fenêtre de recherche (ex: les 7 derniers jours).
  • Personnalisation des catégories de la synthèse (ex: "Annonces majeures", "Secteur public", etc.).
  • Choix du modèle d'IA (Gemini 3.1 Pro, Flash, etc.).
  • Modification du "prompt" de comportement de l'agent de recherche.
• Historique et consultation : Sauvegarde de toutes les synthèses générées pour une consultation ultérieure, avec liens directs vers les articles sources.

🔄 Principaux "User Flows" (Parcours Utilisateur)

1. Onboarding & Configuration initiale

   • L'utilisateur arrive sur la page de connexion et s'authentifie avec Google.
   • Il se rend dans l'onglet Paramètres pour définir son thème de veille, ses catégories et le modèle d'IA souhaité.
   • Il se rend dans l'onglet Sources personnalisées pour ajouter les sites qu'il considère comme incontournables.

2. Génération d'une veille hebdomadaire

   • L'utilisateur clique sur "Nouvelle synthèse".
   • L'application récupère ses paramètres et ses sources, puis interroge l'API Gemini.
   • Un indicateur de chargement patiente pendant que l'IA effectue ses recherches sur le web et rédige le contenu.
   • Une fois terminée, la synthèse est sauvegardée et l'utilisateur est redirigé vers la vue détaillée pour lire son rapport.

3. Consultation de l'historique

   • Depuis l'accueil (Dashboard), l'utilisateur visualise la liste chronologique de ses précédentes synthèses.
   • Il peut cliquer sur l'une d'elles pour la relire ou la supprimer s'il n'en a plus besoin.

🏗️ Architecture de la solution

L'application repose sur une architecture Serverless (BaaS - Backend as a Service). Il n'y a pas de serveur backend Node.js/Express intermédiaire géré manuellement.

• Frontend : Application Single Page (SPA) en React qui gère l'interface, le routage et l'état de l'application.
• Backend / Base de données : Firebase Firestore (NoSQL) est utilisé pour stocker les paramètres, les sources et les synthèses. Les requêtes sont faites directement depuis le client React.
• Sécurité des données : Les firestore.rules garantissent le cloisonnement des données (Multi-tenant). Chaque document possède un champ authorUid ou userId vérifié à chaque requête (isDocOwner()).
• Intelligence Artificielle : Le SDK @google/genai est appelé directement depuis le frontend. L'outil googleSearch est activé dans la configuration du modèle pour permettre le "Grounding" (recherche web en temps réel).

🛠️ Choix technologiques

• Framework UI : React 18+ avec Vite.js pour un build ultra-rapide.
• Langage : TypeScript pour le typage statique et la robustesse du code (src/types.ts centralise les interfaces).
• Styling : Tailwind CSS pour un design utilitaire, responsive et moderne.
• Icônes : lucide-react pour une bibliothèque d'icônes SVG légères et cohérentes.
• Base de données & Auth : Firebase (Firestore + Authentication).
• IA : API Google Gemini (modèles de la série 3.1 et 2.5) avec génération structurée (JSON Schema) pour garantir le formatage des catégories et des articles.
• Utilitaires : date-fns pour le formatage lisible des dates en français.

💡 Divers (Maintenance et Évolution)

Cette section regroupe des informations cruciales pour les développeurs reprenant le projet :

1. Rate Limiting (Limitation de requêtes Gemini)

   • Un limiteur de requêtes (RateLimiter) est implémenté dans src/services/geminiService.ts. Il est configuré pour éviter de dépasser les quotas de l'API Gemini (ex: 29 requêtes par minute). Si vous ajoutez des appels IA supplémentaires, assurez-vous de passer par ce limiteur (await geminiRateLimiter.acquire()).

2. Génération Structurée (JSON Schema)

   • Le service Gemini utilise la fonctionnalité responseSchema pour forcer l'IA à répondre avec un objet JSON strict correspondant aux catégories de l'utilisateur. Si vous modifiez la structure des données (ex: ajout d'une image pour chaque article), vous devez mettre à jour le schéma dans geminiService.ts (newsItemSchema) ET l'interface TypeScript dans types.ts.

3. Règles de sécurité Firestore (firestore.rules)

   • Les règles actuelles sont très strictes. Si vous ajoutez une nouvelle collection (ex: shared_syntheses pour partager des veilles entre utilisateurs), vous devrez écrire de nouvelles règles spécifiques pour autoriser la lecture publique ou par groupe, tout en protégeant l'écriture.

4. Évolutions possibles (Idées)

   • Envoi par email : Ajouter une fonction pour envoyer la synthèse générée par email (nécessiterait une Cloud Function Firebase ou un service comme Resend/SendGrid).
   • Génération automatique (CRON) : Actuellement, la génération est manuelle (déclenchée par l'utilisateur). Pour la rendre 100% automatique tous les lundis matins, il faudrait déporter la logique de geminiService.ts dans une Google Cloud Function déclenchée par Cloud Scheduler.
   • Export PDF/Markdown : Ajouter un bouton sur la vue de détail pour télécharger la synthèse.