10 KiB
10 KiB
Documentation ChartBastan
🎯 Plateforme de prédiction sportive basée sur l'analyse de l'énergie collective des réseaux sociaux
📊 Vue d'ensemble
Type de référentiel: Multi-part (Frontend + Backend séparés)
Parties du projet:
- Partie 1: Frontend Next.js (chartbastan/)
- Partie 2: Backend FastAPI (backend/)
Langage principal:
- Frontend: TypeScript (Next.js 16.1.3)
- Backend: Python (FastAPI 0.128.0)
Architecture: Client-serveur avec REST API
🚀 Démarrage Rapide
Pour Tester l'Application
👉 README de Test Rapide - Guide en 3 étapes pour démarrer l'application
Démarrage rapide:
# Terminal 1 - Backend
cd backend
pip install -r requirements.txt
python -m uvicorn app.main:app --reload --port 8000
# Terminal 2 - Frontend
cd chartbastan
npm install
npm run dev
Accéder à: http://localhost:3000
📚 Documentation Générée
Documentation Principale
- 📖 Structure du Projet - Vue d'ensemble de l'architecture
- 🔧 Métadonnées des Parties - Détails techniques de chaque partie
- 💻 Stack Technologique - Technologies utilisées
- 🏗️ Patterns d'Architecture - Patterns de conception
- 🌳 Analyse de l'Arbre Source - Structure détaillée des fichiers
- 🛠️ Guide de Développement - Guide complet de développement
- 🧪 README de Test Rapide - Guide de testing
Documentation Existante
- 📋 Inventaire de Documentation Existante - 50+ fichiers trouvés
- 👤 Contexte Utilisateur - Objectifs et priorités
🎯 Parties du Projet
Part 1: Frontend (chartbastan/)
Type: Web Application (Next.js 16.1.3)
Technologie principale:
- Framework: Next.js 16.1.3 + TypeScript 5
- UI: Tailwind CSS v4 + shadcn/ui
- State: Zustand 5.0.10 + React Query 5.90.18
- Database: Drizzle ORM 0.44.7 + SQLite
- Visualization: D3.js 7.9.0 + Recharts 3.6.0
Points d'entrée:
- Page d'accueil:
src/app/page.tsx - Layout racine:
src/app/layout.tsx - Configuration:
package.json,tsconfig.json
Port: 3000
Documentation spécifique:
Part 2: Backend (backend/)
Type: API REST (FastAPI 0.128.0)
Technologie principale:
- Framework: FastAPI 0.128.0 + Python 3.11+
- ORM: SQLAlchemy 2.0.45 + Alembic 1.13.0
- Scraping: tweepy 4.14.0 + praw 7.8.1 + feedparser 6.0.11
- ML: vaderSentiment 3.3.2 + textblob 0.17.1
- Queue: pika 1.3.2 (RabbitMQ)
Points d'entrée:
- Application:
app/main.py - API Endpoints:
app/api/ - Configuration:
requirements.txt,alembic.ini
Port: 8000
API Documentation:
- Swagger: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
🔗 Intégration entre Parties
Communication: REST API (HTTP/HTTPS)
Format de données: JSON
Base URL: http://localhost:8000 (développement)
Points d'intégration:
- Authentification - better-auth (frontend) ↔ JWT (backend)
- Données de Matchs -
src/services/matches.ts↔app/api/matches.py - Prédictions -
src/services/predictions.ts↔app/api/predictions.py - Notifications - Workers RabbitMQ ↔ Web Push
📂 Structure du Projet
chartbastan/
├── chartbastan/ # Frontend Next.js
│ ├── src/
│ │ ├── app/ # App Router (pages, layouts)
│ │ ├── components/ # Composants React (72+)
│ │ ├── services/ # Services API (27)
│ │ ├── stores/ # Zustand stores (2)
│ │ ├── hooks/ # React Hooks (9)
│ │ └── lib/ # Utilitaires (7)
│ └── package.json
│
├── backend/ # Backend FastAPI
│ ├── app/
│ │ ├── api/ # Endpoints REST
│ │ ├── models/ # Modèles SQLAlchemy (12)
│ │ ├── schemas/ # Schémas Pydantic (14)
│ │ ├── services/ # Services métier (8)
│ │ ├── scrapers/ # Scrapers (Twitter, Reddit, RSS)
│ │ ├── ml/ # Services ML (sentiment, prédictions)
│ │ ├── workers/ # Workers asynchrones (4)
│ │ └── main.py # Application FastAPI
│ ├── alembic/ # Migrations
│ └── requirements.txt
│
├── _bmad-output/ # Documentation de planification
│ ├── planning-artifacts/ # PRD, Architecture, Epics
│ └── implementation-artifacts/ # 38 fichiers d'implémentation
│
└── docs/ # Documentation (ce dossier)
📖 Documentation de Planification et Implémentation
Artefacts de Planification
- 📋 PRD Complet - Product Requirements Document
- 🏗️ Architecture - Documentation architecturale
- 📝 Epics - 9 épics complétés
- 🎨 UX Design Directions
- 🎨 UX Design Specification
Artefacts d'Implémentation
🛠️ Dossier d'Artefacts - 38 fichiers de documentation d'implémentation détaillée
Épics complétés:
- Authentification des utilisateurs
- Collecte de données (Twitter, Reddit, RSS)
- Analyse de sentiment et énergie collective
- Système de prédictions ML
- Dashboard principal en temps réel
- Système de paris et prédictions utilisateurs
- Gamification (badges, classements, parrainage)
- Notifications push et alertes
- API publique et calendrier énergétique
🚀 Getting Started
1. Pour Tester l'Application
👉 README de Test Rapide - Guide en 3 étapes
2. Pour le Développement
👉 Guide de Développement - Guide complet de développement
Étapes rapides:
- Installer les dépendances:
pip install -r requirements.txtetnpm install - Configurer les variables d'environnement (.env et .env.local)
- Démarrer le backend:
python -m uvicorn app.main:app --reload --port 8000 - Démarrer le frontend:
npm run dev - Ouvrir http://localhost:3000
3. Pour Comprendre l'Architecture
👉 Patterns d'Architecture - Patterns de conception détaillés
👉 Stack Technologique - Technologies utilisées
4. Pour Explorer le Code
👉 Analyse de l'Arbre Source - Structure détaillée des fichiers
👉 Structure du Projet - Vue d'organisation
🧪 Testing
Fonctionnalités à Tester
Voir le README de Test Rapide pour la checklist complète:
- ✅ Authentification (inscription, login, déconnexion)
- ✅ Dashboard principal (matchs, graphiques)
- ✅ Prédictions (faire une prédiction, voir l'énergie)
- ✅ Classement (Top 100, rang personnel)
- ✅ Badges et gamification
- ✅ Notifications
- ✅ Historique des prédictions
- ✅ Parrainage
- ✅ Comparaison énergie vs stats
- ✅ Calendrier énergétique
Tests Automatisés
Frontend:
cd chartbastan
npm run test
Backend:
cd backend
pytest tests/ -v
🛠️ Scripts et Commandes
Frontend (chartbastan/)
| Commande | Description |
|---|---|
npm run dev |
Démarrer le serveur de développement (port 3000) |
npm run build |
Build de production |
npm run start |
Démarrer le serveur de production |
npm run lint |
Exécuter ESLint |
npm run type-check |
Vérifier les types TypeScript |
npm run test |
Exécuter les tests Vitest |
Backend (backend/)
| Commande | Description |
|---|---|
python -m uvicorn app.main:app --reload --port 8000 |
Démarrer le serveur FastAPI |
flake8 . |
Linting du code Python |
black . |
Formatage du code Python |
pytest tests/ |
Exécuter les tests unitaires |
alembic upgrade head |
Appliquer toutes les migrations |
📚 Ressources de Référence
Documentation API
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
Documentation Externe
- Next.js: https://nextjs.org/docs
- FastAPI: https://fastapi.tiangolo.com/
- React: https://react.dev/
- Tailwind CSS: https://tailwindcss.com/docs
- Drizzle ORM: https://orm.drizzle.team/
- SQLAlchemy: https://docs.sqlalchemy.org/
📊 Statut du Projet
Phase: Testing (tous les épics complétés)
- ✅ PRD complet
- ✅ Architecture implémentée
- ✅ 9 épics complétés
- ✅ Frontend et Backend prêts
- 🔄 Testing en cours
Technologie:
- Frontend: Next.js 16.1.3 + TypeScript 5
- Backend: FastAPI 0.128.0 + Python 3.11+
- Database: SQLite (Phase 1) → PostgreSQL (Phase 2+)
- API: REST + Swagger documentation
🐛 Dépannage
Pour les problèmes courants, consulter:
Problèmes fréquents:
- Backend ne démarre pas → Vérifier le port 8000
- Frontend ne démarre pas → Nettoyer node_modules et réinstaller
- Erreur de connexion → Vérifier que backend tourne et .env.local est configuré
- Base de données vide → Exécuter
alembic upgrade head
🤝 Contribution
Le projet est complet et en phase de testing. Pour contribuer:
- Fork le repository
- Créer une branche
feature/nouvelle-fonctionnalité - Développer la fonctionnalité
- Commit avec des messages clairs
- Push et créer une Pull Request
📄 Licence
Ce projet est sous license MIT.
📞 Contact
Pour toute question:
- Consulter les artefacts d'implémentation:
_bmad-output/implementation-artifacts/ - Vérifier la documentation API: http://localhost:8000/docs
- Consulter le README principal:
chartbastan/README.md
Date de création: 2026-01-18 Version: 0.1.0 Statut: Testing (tous les épics complétés) ✅