# 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](./README-TEST.md)** - Guide en 3 étapes pour démarrer l'application

**Démarrage rapide:**

```bash
# 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](./project-structure.md)** - Vue d'ensemble de l'architecture
- 🔧 **[Métadonnées des Parties](./project-parts-metadata.md)** - Détails techniques de chaque partie
- 💻 **[Stack Technologique](./technology-stack.md)** - Technologies utilisées
- 🏗️ **[Patterns d'Architecture](./architecture-patterns.md)** - Patterns de conception
- 🌳 **[Analyse de l'Arbre Source](./source-tree-analysis.md)** - Structure détaillée des fichiers
- 🛠️ **[Guide de Développement](./development-guide.md)** - Guide complet de développement
- 🧪 **[README de Test Rapide](./README-TEST.md)** - Guide de testing

### Documentation Existante

- 📋 **[Inventaire de Documentation Existante](./existing-documentation-inventory.md)** - 50+ fichiers trouvés
- 👤 **[Contexte Utilisateur](./user-provided-context.md)** - 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:**
- 📄 [README Frontend](../chartbastan/README.md)

---

### 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:**
1. **Authentification** - better-auth (frontend) ↔ JWT (backend)
2. **Données de Matchs** - `src/services/matches.ts` ↔ `app/api/matches.py`
3. **Prédictions** - `src/services/predictions.ts` ↔ `app/api/predictions.py`
4. **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](../_bmad-output/planning-artifacts/prd.md)** - Product Requirements Document
- 🏗️ **[Architecture](../_bmad-output/planning-artifacts/architecture.md)** - Documentation architecturale
- 📝 **[Epics](../_bmad-output/planning-artifacts/epics.md)** - 9 épics complétés
- 🎨 **[UX Design Directions](../_bmad-output/planning-artifacts/ux-design-directions.html)**
- 🎨 **[UX Design Specification](../_bmad-output/planning-artifacts/ux-design-specification.md)**

### Artefacts d'Implémentation

🛠️ **[Dossier d'Artefacts](../_bmad-output/implementation-artifacts/)** - 38 fichiers de documentation d'implémentation détaillée

**Épics complétés:**
1. Authentification des utilisateurs
2. Collecte de données (Twitter, Reddit, RSS)
3. Analyse de sentiment et énergie collective
4. Système de prédictions ML
5. Dashboard principal en temps réel
6. Système de paris et prédictions utilisateurs
7. Gamification (badges, classements, parrainage)
8. Notifications push et alertes
9. API publique et calendrier énergétique

---

## 🚀 Getting Started

### 1. Pour Tester l'Application

👉 **[README de Test Rapide](./README-TEST.md)** - Guide en 3 étapes

### 2. Pour le Développement

👉 **[Guide de Développement](./development-guide.md)** - Guide complet de développement

**Étapes rapides:**
1. Installer les dépendances: `pip install -r requirements.txt` et `npm install`
2. Configurer les variables d'environnement (.env et .env.local)
3. Démarrer le backend: `python -m uvicorn app.main:app --reload --port 8000`
4. Démarrer le frontend: `npm run dev`
5. Ouvrir http://localhost:3000

### 3. Pour Comprendre l'Architecture

👉 **[Patterns d'Architecture](./architecture-patterns.md)** - Patterns de conception détaillés

👉 **[Stack Technologique](./technology-stack.md)** - Technologies utilisées

### 4. Pour Explorer le Code

👉 **[Analyse de l'Arbre Source](./source-tree-analysis.md)** - Structure détaillée des fichiers

👉 **[Structure du Projet](./project-structure.md)** - Vue d'organisation

---

## 🧪 Testing

### Fonctionnalités à Tester

Voir le **[README de Test Rapide](./README-TEST.md)** 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:**
```bash
cd chartbastan
npm run test
```

**Backend:**
```bash
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:

- **[Guide de Développement - Dépannage](./development-guide.md#dépannage)**
- **[README de Test Rapide - Dépannage](./README-TEST.md#-dépannage)**

**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:

1. Fork le repository
2. Créer une branche `feature/nouvelle-fonctionnalité`
3. Développer la fonctionnalité
4. Commit avec des messages clairs
5. 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) ✅