---
stepsCompleted: ['step-01-init', 'step-02-discovery', 'step-03-success', 'step-04-journeys', 'step-05-domain', 'step-06-innovation', 'step-07-project-type', 'step-08-scoping', 'step-09-functional', 'step-10-nonfunctional', 'step-11-polish']
inputDocuments:
  - brainstorming-session-2026-01-15.md
workflowType: 'prd'
briefCount: 0
researchCount: 0
brainstormingCount: 1
projectDocsCount: 0
classification:
  projectType: web_app
  domain: gambling_betting
  complexity: high
  projectContext: greenfield
  techStack:
    frontend:
      framework: Next.js 16
      styling: Tailwind 4
      ui: shadcn/ui
    backend:
      primary: Python FastAPI
      purpose: Core analytics, ML, sentiment analysis
    secondary: Node.js (Next.js API routes)
    purpose: Lightweight API, authentication
---

# Product Requirements Document - chartbastan

**Author:** Ramez
**Date:** 2026-01-15

## Success Criteria

### User Success

**Moment "Aha !" clé :** L'utilisateur voit une prédiction avec haut niveau de confiance (ex: 75%+) et cette prédiction se révèle CORRECTE.

**Métriques spécifiques :**
- Utilisateur consulte ≥ 3 prédictions consécutivement
- Utilisateur retourne sur l'app dans les 7 jours après première consultation
- Taux de conversion gratuit → premium : > 5% après 30 jours d'utilisation
- 80%+ des beta utilisateurs trouvent l'interface "facile à utiliser"

### Business Success

**Phase 1 (Backtesting & Validation) :**
- Taux de précision > 60% sur 100+ matchs historiques
- Preuve publique publiée (Medium, Reddit) avec résultats transparents
- ≥ 100 inscriptions sur liste d'attente via landing page

**Phase 2 (Lancement Beta) :**
- 500 utilisateurs beta actifs
- Engagement : > 20% DAU/MAU ratio
- ≥ 50 conversions premium (2.5% conversion rate)

**Phase 3 (Lancement Public) :**
- 2,000-5,000 utilisateurs en 2 semaines
- Viralité : chaque utilisateur invite en moyenne ≥ 2 amis
- Taux de précision en production ≥ 60% (maintenu)

**Projection Mois 6 :**
- 20,000 utilisateurs totaux
- 1,000 utilisateurs premium (19.99€/mois)
- 26,000€/mois de revenus (20,000€ premium + 6,000€ publicités)
- Seuil de rentabilité : 3 abonnés premium = rentable dès le début

### Technical Success

**Performance :**
- Dashboard mis à jour en < 3 secondes
- Analyse de 1000+ tweets en < 1 seconde
- Scraping Twitter stable sur 24h sans interruption
- Collecte réussie sans dépasser les limits de l'API publique

**Qualité des prédictions :**
- Backtesting sur ≥ 100 matchs historiques
- Taux de précision ≥ 60% (seuil de validation)
- Taux de précision < 55% = REVISER l'approche
- Confidence Meter précis : ±5% du taux de réussite réel

**Architecture :**
- API Python FastAPI stable (uptime > 99.5%)
- Frontend Next.js 16 responsive (Lighthouse score > 90)
- Base de données optimisée (SQLite suffisant pour Phase 1)
- Système de queue asynchrone (RabbitMQ) pour pics de charge

### Measurable Outcomes

**Phase 1 (Semaines 1-4) :**
- Algorithme de sentiment fonctionnel avec VADER/textblob
- Système de backtesting sur 100 matchs
- Taux de précision > 60% = VALIDÉ pour Phase 2
- Landing page avec capture emails
- Documentation publique des résultats sur Medium/Reddit

**Phase 2 (Semaines 5-8) :**
- Dashboard en temps réel (Next.js + shadcn/ui)
- 500 utilisateurs beta actifs
- Système de classement/gamification
- Notifications push pour changements majeurs
- Métriques détaillées pour utilisateurs premium

**Phase 3 (Mois 3-6) :**
- 5,000-20,000 utilisateurs
- Viralité auto-entretenue (parrainage, partage réussites)
- Taux de précision maintenu ≥ 60% en production
- Extension multi-sports (football + autres)

---

## Product Scope

### MVP - Minimum Viable Product

**Phase 1 (Semaines 1-4) - Backtesting & Validation :**
- Scrapping Twitter via API publique (1000 requêtes/heure gratuit)
- Algorithme de sentiment simple (VADER)
- Formule : Score = (Positif - Négatif) × Volume × Viralité
- Système de backtesting sur 100 matchs historiques (Ligue 1, Premier League, Champions League)
- Taux de précision > 60% = VALIDÉ
- Landing page simple avec capture d'emails (Mailchimp gratuit)
- Article/blog avec preuve de concept publique

**Contraintes MVP :**
- Budget minimal (10-20€/mois)
- Python (FastAPI) + Next.js 16 + Tailwind 4 + shadcn/ui
- Base de données SQLite (gratuit)
- Focus UNIQUE sur Football pour Phase 1
- Pas d'app mobile complexe (web app responsive suffisant)

### Growth Features (Post-MVP)

**Phase 2 (Semaines 5-8) - Lancement Beta :**
- Dashboard de prédiction en temps réel (Next.js + D3.js)
- Confidence Meter (0-100%)
- Visualisation de l'énergie collective (graphique de vague/diagramme de chaleur)
- Historique temporel (Flashback des 24h avant match)
- Système de classement/gamification (Top 100 utilisateurs)
- Programme de parrainage (invite 3 amis = 1 mois premium GRATUIT)
- Notifications push pour changements majeurs
- Comparaison Énergie vs Stats Traditionnelles
- Calendrier énergétique de matchs
- Version gratuite (1-2 prédictions/jour) + Version premium (19.99€/mois)

**Phase 3 (Mois 3-6) - Lancement Public & Croissance :**
- Système de partages automatiques de réussites
- Badges et réalisations partageables
- Marketing viral via influenceurs sportifs
- Live Tweet des prédictions pendant grands matchs
- Testimonials vidéo des gagnants
- Optimisation SEO pour traffic organique

### Vision (Future)

**Mois 6+ - Features Avancées Phase 2 :**
- Prédictions long-term (saisons complètes, classements finals)
- Détection de momentum énergétique (équipes en forme)
- Détection d'anomalies énergétiques (dark horses)
- Alertes d'énergie émergente (avantage temporel)
- Comparaison transparente vs autres méthodes (Stats, Cotes, Intuition)
- Mode Prophète pour prédictions personnalisées aux top utilisateurs
- Analyse de sentiment des joueurs eux-mêmes (Twitter accounts des joueurs)
- Historique de l'énergie pour analyse long-term
- Système de simulation de scénarios pour utilisateurs avancés
- Cross-sport predictions pour arbitrage (football, politique, marchés financiers)

**Internationalisation (Phase 2+) :**
- Multi-langue (français, anglais, espagnol, allemand, italien, portugais)
- Lancement progressif par pays (France → Espagne → Italie → Allemagne)
- Scrapping multi-plateforme par région (Twitter, Weibo, VK)
- Time-zone aware avec devise locale

**API Publique (Phase 2+) :**
- Intégration API pour développeurs tiers
- Système de souscription prémium pour données avancées
- Partners médias avec analytics prédictionnels

## User Journeys

### Persona 1 : Thomas - Le Parieur Passionné

**Situation :**
Thomas, 28 ans, supporter du PSG. Parie occasionnellement (2-3 fois par mois) sur des matchs importants. A perdu 400€ le mois dernier en misant sur des équipes favorites sans vraie stratégie.

**But :**
Il veut augmenter ses chances de gagner en utilisant des données objectives plutôt que son instinct ou les cotes traditionnelles qu'il ne comprend pas vraiment.

**Obstacle :**
Les sites de paris sont confus, les cotes sont opaques, et il n'a pas les compétences techniques pour analyser les stats des joueurs ou l'historique des matchs.

**Parcours Narratif - Histoire de Thomas :**

**Scène d'ouverture :**
Un jeudi soir, Thomas scrolle Twitter sur son canapé. Il voit un tweet viral : "Comment l'énergie collective des supporters sur Twitter prédit 65% des résultats de football." Intrigué, il clique sur le lien.

**Action Montante (Étape 1 - Découverte) :**
Il atterrit sur une landing page épurée avec des résultats de backtesting. Il voit un tableau de 100 matchs récents avec prédictions et résultats réels. Le taux de réussite est de 63%. Thomas se dit : "C'est mieux que Polymarket qui a seulement 55% de précision." Il inscrit son email dans la liste d'attente.

**Action Montante (Étape 2 - Premier Accès) :**
Deux jours plus tard, il reçoit un email : "Ton accès est prêt ! Tu as 1 prédiction gratuite par jour." Il se connecte. L'interface est ultra-simple : un match PSG vs Marseille ce soir avec un "Confidence Meter" à 78% pour PSG. En dessous, une vague visuelle montre l'énergie collective monter doucement depuis 2 heures.

**Climax - Le Moment "Aha !" :**
Thomas regarde le match sur TV. À la 75ème minute, PSG marque le deuxième but. Son téléphone vibre : notification de l'app : "Score de confiance maintenant 82% - Énergie collective stabilisée." Thomas réalise que l'app n'avait pas seulement prédit le résultat, mais montrait l'évolution de l'énergie en temps réel. Il gagne son pari de 50€.

**Résolution - Nouvelle Réalité :**
Thomas revient sur l'app le lendemain. Il regarde son historique personnel : 3 prédictions consultées, 2 correctes (67%). Il comprend que ce n'est pas parfait, mais c'est mieux que son instinct. Il reçoit une notification : "Invite 3 amis et obtiens 1 mois premium GRATUIT." Il partage sur son groupe WhatsApp de supporters. Trois amis s'inscrivent. Thomas obtient son mois premium et découvre les fonctionnalités avancées.

---

### Persona 2 : Marie - La Parieuse Sérieuse

**Situation :**
Marie, 34 ans, analyste financière. Parie régulièrement sur le football depuis 5 ans. A perdu 2,000€ l'année dernière mais y voit un investissement, pas du gambling.

**But :**
Elle veut des métriques détaillées, des données historiques, et des analyses avancées pour prendre des décisions informées. Elle est prête à payer pour de la valeur réelle.

**Obstacle :**
Les sites de paris ne lui donnent que des cotes superficielles. Elle veut comprendre POURQUOI une prédiction est faite, pas juste QUOI parier.

**Parcours Narratif - Histoire de Marie :**

**Scène d'ouverture :**
Marie lit un article sur Medium : "Pourquoi l'énergie collective des supporters prédit mieux que l'analyse statistique traditionnelle." Elle est sceptique mais curieuse - elle connait bien les analyses financières. Elle s'inscrit sur l'app pour tester.

**Action Montante (Étape 1 - Version Gratuite) :**
Pendant 2 semaines, elle utilise la version gratuite (1 prédiction par jour). Elle teste 14 prédictions sur 14 jours. Taux de réussite : 64%. Elle est impressionnée mais frustrée - l'accès limité l'empêche de vraiment exploiter l'outil.

**Action Montante (Étape 2 - Conversion Premium) :**
Le 15ème jour, elle reçoit un email : "Marie, vous avez consulté 15 prédictions avec 64% de réussite. Passez Premium pour des analyses illimitées et métriques détaillées." Elle regarde les avantages : accès temps réel, alertes push, dashboard avancé, métriques détaillées. Elle se dit : "19.99€/mois, c'est moins que ce que je perds en un mauvais pari." Elle s'abonne.

**Climax - La Révélation Premium :**
Marie accède au dashboard avancé. Elle découvre une vue qu'elle n'avait jamais vue :
- Graphique d'énergie collective sur 24h pour chaque équipe
- Comparaison côte à côte : Prédiction Énergie vs Stats Traditionnelles vs Cotes
- Alertes programmées : "Énergie de l'équipe X s'effondre -3% en 30 min"
- Son historique personnel avec ROI détaillé : +240€ depuis inscription

Pour le match Chelsea vs Arsenal, elle voit une anomalie : Chelsea a 85% d'énergie collective mais les cotes favorisent Arsenal. Elle regarde l'actualité intégrée : un star player d'Arsenal est blessé, mais les médias ne l'ont pas encore annoncé. Marie mise sur Chelsea avec confiance. Chelsea gagne 3-0.

**Résolution - Nouvelle Réalité :**
Après 2 mois de Premium, Marie a un ROI de +18%. Elle recommande l'app à ses collègues traders. Elle devient une "Top Prophète" dans le classement public, ce qui augmente sa crédibilité dans sa communauté de parieurs. Elle reçoit des demandes d'autres utilisateurs qui veulent ses conseils.

---

### Persona 3 : Julien - Le Testeur Beta Technique

**Situation :**
Julien, 24 ans, développeur Python full-stack. Passionné de football et de data science. A entendu parler du projet sur Reddit.

**But :**
Il veut participer à la beta parce qu'il est fasciné par l'innovation technique. Il espère aussi contribuer avec des feedbacks constructifs.

**Obstacle :**
Il ne sait pas si l'app est stable, si les prédictions sont réellement précises, ou si c'est juste une autre fausse promesse dans le monde du betting.

**Parcours Narratif - Histoire de Julien :**

**Scène d'ouverture :**
Julien lit un post sur r/DataScience : "Nouveau projet : Analyser l'énergie collective Twitter pour prédire les résultats de football avec 63% de précision." Il commente : "C'est bluffant mais j'ai besoin de voir le code." Le fondateur répond : "Rejoins la beta, tu auras accès à l'API documentation."

**Action Montante (Étape1 - Onboarding Beta) :**
Julien s'inscrit à la beta limitée. Il reçoit immédiatement :
- Accès au dashboard de prédiction
- Documentation API publique
- Formulaire de feedback structuré
- Invitation sur Discord pour testers beta

Il teste la première prédiction pour Real Madrid vs Barça. Dashboard met 2.5 secondes à charger (acceptable mais perfectible). Confidence Meter à 71%. Julien note le feedback.

**Action Montante (Étape 2 - Exploration Technique) :**
Il connecte son propre script Python à l'API publique. Il teste 50 requêtes par minute pendant 1 heure. Rate limiting fonctionne correctement. Il analyse les données JSON reçues :
```json
{
  "match": "Real Madrid vs Barça",
  "energy_score": 0.71,
  "confidence": 71,
  "sentiment_breakdown": {
    "positive": 654,
    "negative": 234,
    "neutral": 123
  },
  "viral_coefficient": 3.2,
  "time_weight": 0.85
}
```

Julien est impressionné par la structure de données claire et la transparence de l'algorithme.

**Climax - Le Bug Critique :**
Pendant un match PSG vs Lyon, Julien remarque une anomalie : l'énergie collective chute brutalement de 82% à 45% en 2 minutes, mais le match continue normalement. Il suspecte un bug dans l'algorithme de pondération temporelle. Il ouvre le formulaire de feedback beta, capture les screenshots, et décrit le problème avec détails techniques : timestamps, JSON brut, comportement attendu vs observé.

**Résolution - Nouvelle Réalité :**
24h plus tard, il reçoit un email : "Merci Julien ! Tu as trouvé un bug dans notre algorithme de filtrage du chaos. On l'a corrigé et ta version de beta a été mise à jour. Comme remerciement, tu as 3 mois premium gratuits." Julien teste à nouveau le match PSG vs Lyon - le bug est résolu. Il poste sur Reddit : "L'équipe de dev est réactive et transparente. Le projet a du potentiel." Son post génère 47 inscriptions sur la liste d'attente.

---

### Persona 4 : Sophie - Admin & Opérations

**Situation :**
Sophie, 29 ans, ingénieure DevOps. Responsable de la stabilité et de la performance du système.

**But :**
Maintenir l'uptime > 99.5%, surveiller les API externes (Twitter, Reddit, RSS), et résoudre les incidents avant qu'ils n'affectent les utilisateurs.

**Obstacle :**
Le système dépend de trois API externes (Twitter, Reddit, RSS) avec des rate limits différents et des patterns de panne imprévisibles.

**Parcours Narratif - Histoire de Sophie :**

**Scène d'ouverture :**
Sophie arrive au bureau un lundi matin à 8h30. Son premier réflexe : ouvrir le dashboard de monitoring. Tout est vert - uptime 99.7% sur les 7 derniers jours. Le système de queue asynchrone (RabbitMQ) gère correctement les pics de charge du week-end.

**Action Montante (Étape 1 - Monitoring Quotidien) :**
Elle vérifie les métriques clés :
- **Twitter API** : 850 req/heure sur 1000 disponibles (85% utilisation)
- **Reddit API** : Pas de rate limiting (API généreuse)
- **RSS Feeds** : 100% succès
- **Temps de réponse** : 2.3s moyen (< 3s requis)
- **Taux de précision** : 64% sur les 50 derniers matchs

Tout semble nominal. Mais elle remarque une tendance inquiétante : l'utilisation de l'API Twitter augmente progressivement depuis 3 jours (70% → 75% → 82% → 85%).

**Action Montante (Étape 2 - Analyse de Tendance) :**
Sophie analyse les logs détaillés. Elle découvre que le volume de tweets par match a augmenté de 40% depuis une semaine - c'est saison de Champions League. Le système de scraping va bientôt dépasser le rate limit de Twitter.

Elle identifie trois options :
1. Optimiser les requêtes Twitter (réduire la quantité)
2. Prioriser les matchs VIP (tous les matchs, moins de profondeur par match)
3. Passer à API Twitter payante (mais budget Phase 1 = 0)

Elle décide de contacter l'équipe produit pour validation.

**Climax - L'Incident Critique :**
Mercredi soir, pendant un match PSG vs Bayern (grand événement), Sophie reçoit une alerte automatique sur son téléphone : "⚠️ CRITICAL - Twitter API rate limit dépassé - Scraping STOPPÉ."

Elle se connecte immédiatement. Le scraping Twitter est arrêté depuis 18:42. Les prédictions continuent mais avec uniquement Reddit + RSS, ce qui baisse la confiance de 67% à 58%.

Sophie exécute le plan d'urgence qu'elle a préparé :
1. Active le mode "dégradé" (Reddit + RSS uniquement)
2. Ajoute une bannière dans l'app : "Données Twitter tempor. indisponibles - Prédictions avec confiance réduite"
3. Envoie notification aux utilisateurs premium concernés
4. Analyse les logs pour comprendre si c'est une anomalie ou une nouvelle normalité

**Résolution - Nouvelle Réalité :**
Le lendemain, Sophie analyse l'incident :
- Cause : Volume record de tweets pendant PSG vs Bayern (127,000 tweets/h vs moyenne 85,000/h)
- Impact : Prédictions avec 58% de confiance vs 67% habituel
- Durée : 47 minutes

Elle propose une solution permanente :
- **Optimisation intelligente** : Scraper uniquement les tweets avec engagement élevé (>10 retweets/likes)
- **Mode priorité dynamique** : Les matchs VIP (PSG, Bayern, Real Madrid, Barça) ont la priorité sur les autres
- **Alerte prédictive** : Alerter quand l'utilisation > 90% pendant 10 minutes consécutives

L'équipe produit valide. Sophie implémente en 2 jours. La prochaine période de pic est gérée sans incident.

---

### Persona 5 : Lucas - Support Client

**Situation :**
Lucas, 26 ans, support client. Répond aux tickets d'aide, guide les utilisateurs, et résout les problèmes courants.

**But :**
Aider les utilisateurs rapidement, réduire le taux de churn, et collecter des feedbacks constructifs pour l'équipe produit.

**Obstacle :**
L'app a deux types d'utilisateurs très différents (gratuits vs premium) avec des attentes différentes. Les questions techniques peuvent être complexes.

**Parcours Narratif - Histoire de Lucas :**

**Scène d'ouverture :**
Lucas ouvre son dashboard de support à 9h du matin. 12 nouveaux tickets dans la file d'attente depuis la veille. Il classe par priorité : 2 critiques, 4 importants, 6 normaux.

**Action Montante (Étape 1 - Support Premium) :**
Le premier ticket est critique : "User premium depuis 3 mois - Dashboard affiche 'Erreur 500' depuis 2h - En pleine période de pari sur Champions League !"

Lucas identifie immédiatement : c'est un utilisateur premium (ticket marqué avec badge ⭐). Il vérifie d'abord s'il y a des incidents système connus. Monitoring montre "All Systems Green". C'est donc un problème spécifique à cet utilisateur.

Il répond dans les 5 minutes (SLA premium) :
> "Bonjour Marc ! Je suis Lucas du support Premium. Je vois que votre dashboard rencontre une erreur 500. Pourriez-vous me dire : 1) Sur quel navigateur êtes-vous ? 2) À quel moment exactement l'erreur apparaît ? Je vais prioriser votre résolution."

Marc répond : "Chrome, j'essaie de charger l'historique de mes prédictions des 30 derniers jours."

Lucas teste sur son propre compte avec le même scénario. Il reproduit l'erreur ! C'est un bug récent, pas un problème spécifique à Marc.

**Action Montante (Étape 2 - Escalade Technique) :**
Il identifie le pattern : seuls les utilisateurs premium depuis plus de 3 mois sont affectés quand ils chargent l'historique complet. C'est probablement une base de données qui ne gère pas correctement les requêtes massives.

Il escalade à l'équipe technique avec priorité P1 (bug critique) :
```
Bug: Dashboard Premium - Erreur 500 sur historique 30+ jours
Impact: Utilisateurs premium > 3 mois
Reproduction: Charger historique complet
Urgency: P1 - Période de pari active
```

Pendant que l'équipe corrige, Lucas prépare une réponse proactive : il contacte tous les utilisateurs premium concernés (identifiés dans la base de données) avec :
> "Nous avons identifié un bug sur l'historique. Notre équipe corrige activement. En attendant, utilisez l'historique des 7 derniers jours (fonctionnel). Désolé pour l'inconvénient !"

**Climax - Le Feedback Constructif :**
Une fois le bug résolu, Lucas reçoit un email de Marc :
> "Merci pour la réponse rapide et pour avoir prévenu les autres. J'ai perdu 1 pari sur 3 ce week-end, mais votre transparence m'a donné confiance dans l'équipe. Une suggestion : vous pourriez montrer un indicateur de performance sur l'historique (temps de chargement prévu)."

Lucas documente ce feedback dans le système de tickets. Il voit que cette suggestion est venue 3 fois dans le dernier mois. Il la tagge pour l'équipe produit : "Feature Request - Performance Indicator sur Historique".

**Résolution - Nouvelle Réalité :**
Après 6 mois, Lucas observe une amélioration : le taux de tickets a diminué de 35% car l'équipe produit a implémenté les features demandées par les utilisateurs. Les utilisateurs premium restent en moyenne 18 mois (vs 12 mois avant les améliorations).

---

### Journey Requirements Summary

**Capacités Révélées par les Parcours :**

**Pour Utilisateur Primaire (Thomas/Marie) :**
- Landing page avec backtesting visible
- Dashboard simple et intuitif (Mode Débutant)
- Confidence Meter visuel (0-100%)
- Visualisation de l'énergie collective (vague/graphique)
- Historique personnel avec ROI
- Système de classement/gamification
- Programme de parrainage
- Notifications push
- Mode Expert avec métriques détaillées

**Pour Utilisateur Beta (Julien) :**
- Documentation API publique
- Formulaires de feedback structurés
- Channels de communication (Discord, formulaire)
- Système de récompenses pour feedbacks
- Rate limiting robuste
- Communication transparente

**Pour Admin/Opérations (Sophie) :**
- Dashboard de monitoring temps réel
- Alertes automatiques multi-canal
- Logs détaillés et analyse d'incidents
- Configuration dynamique de priorités
- Plans d'urgence et modes dégradés
- Communication transparente avec utilisateurs

**Pour Support (Lucas) :**
- Système de tickets avec SLA différenciés
- Dashboard de support avec classification
- Système d'escalade technique
- Communication proactive
- Système de feedbacks structuré
- Base de connaissance

**Pour Sources de Données (Hybride) :**
- Scrapping Twitter API (60% pondération)
- Scrapping Reddit API (25% pondération)
- Scrapping RSS Feeds (15% pondération)
- Fusion intelligente avec pondération
- Rate limiting robuste et priorisation dynamique
