# Stack Technologique - ChartBastan

## Vue d'ensemble

Le projet ChartBastan utilise une stack moderne full-stack avec:
- **Frontend:** Next.js 16 avec TypeScript
- **Backend:** FastAPI avec Python 3.11+
- **Base de données:** SQLite (développement) → PostgreSQL (production)
- **Communication:** REST API
- **Message Queue:** RabbitMQ (pour workers asynchrones)

---

## Partie 1: Frontend (chartbastan/)

### Framework & Language

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Framework | Next.js | 16.1.3 | Framework React moderne avec SSR, SSG, et App Router |
| Language | TypeScript | 5.0 | Typage statique pour la fiabilité du code |
| Runtime | Node.js | 20+ | Environment JavaScript moderne |

### UI & Styling

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| CSS Framework | Tailwind CSS | v4 | Utilitaire-first CSS, développement rapide |
| UI Library | shadcn/ui | - | Composants Radix UI accessibles et personnalisables |
| Icons | Lucide React | 0.562.0 | Icônes SVG légères et cohérentes |
| Animation | Framer Motion | 12.26.2 | Animations fluides et performantes |
| Pull-to-refresh | react-pull-to-refresh | 2.0.1 | UX mobile native pour rafraîchir |

### State Management

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| State Store | Zustand | 5.0.10 | State management léger et simple |
| Data Fetching | React Query (@tanstack/react-query) | 5.90.18 | Cache, sync, et gestion des appels API |

### Database & ORM

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Database | SQLite | better-sqlite3 12.6.2 | Base légère pour développement |
| ORM | Drizzle ORM | 0.44.7 | ORM moderne type-safe avec SQL pur |
| Migrations | Drizzle Kit | 0.31.8 | Génération de migrations et schéma |

### Visualization

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Charts | Recharts | 3.6.0 | Graphiques React déclaratifs |
| Advanced Viz | D3.js | 7.9.0 | Visualisations complexes et personnalisées |
| Types | @types/d3 | 7.4.3 | Typage TypeScript pour D3 |

### Authentication

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Auth | better-auth | 1.4.14 | Solution d'authentification moderne pour Next.js |
| Password Hashing | bcryptjs | 3.0.3 | Hashage sécurisé des mots de passe |

### Notifications

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Web Push | web-push | 3.6.7 | Notifications push web standard W3C |
| Types | @types/web-push | 3.6.4 | Typage TypeScript |

### Validation & Forms

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Validation | Zod | 4.3.5 | Validation de schéma avec TypeScript |

### Messaging

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Redis Client | ioredis | 5.9.2 | Client Redis pour pub/sub et cache |

### Utilities

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Class Variance | class-variance-authority | 0.7.1 | Gestion des variantes de composants |
| clsx | clsx | 2.1.1 | Concaténation de classes conditionnelle |
| tailwind-merge | tailwind-merge | 3.4.0 | Fusion intelligente de classes Tailwind |

### Development Tools

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Linter | ESLint | 9 | Linting JavaScript/TypeScript |
| Testing | Vitest | 4.0.17 | Framework de test rapide et moderne |
| Testing Library | @testing-library/react | 16.3.1 | Tests de composants React |
| Testing Library | @testing-library/user-event | 14.6.1 | Simulation d'interactions utilisateur |
| Testing Library | @testing-library/jest-dom | 6.9.1 | Matchers DOM pour Jest/Vitest |
| Happy DOM | happy-dom | 20.3.1 | Léger DOM implementation pour tests |
| JSDOM | jsdom | 27.4.0 | DOM implementation pour tests |

### Architecture Pattern

**Type:** Component-based / App Router (Next.js 16)

**Caractéristiques:**
- App Router avec Server Components
- Client Components pour l'interactivité
- API Routes pour backend intégré
- Middleware pour authentification et routing
- Streaming et Suspense pour UX optimisée

**Structure:**
- `src/app/` - App Router (routes, layouts, pages)
- `src/components/` - Composants réutilisables
- `src/services/` - Services API et logique métier
- `src/hooks/` - React Hooks personnalisés
- `src/stores/` - Zustand stores
- `src/lib/` - Utilitaires et helpers

---

## Partie 2: Backend (backend/)

### Framework & Server

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Framework | FastAPI | 0.128.0 | API moderne, rapide, avec documentation auto |
| ASGI Server | Uvicorn | 0.30.0 | Server ASGI haute performance |
| Language | Python | 3.11+ | Version moderne avec typage amélioré |

### Database & ORM

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| ORM | SQLAlchemy | 2.0.45 | ORM Python mature et flexible |
| Migrations | Alembic | 1.13.0 | Outil de migration de base de données |

### Validation & Settings

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Validation | Pydantic | 2.7.0 | Validation de données avec Python |
| Settings | Pydantic Settings | 2.3.0 | Gestion des variables d'environnement |
| Email Validation | email-validator | 2.1.0 | Validation d'adresses email |

### Data Scraping

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Twitter API | tweepy | 4.14.0 | Client Python pour l'API Twitter v2 |
| Reddit API | praw | 7.8.1 | Python Reddit API Wrapper |
| RSS Parser | feedparser | 6.0.11 | Parser RSS/Atom feeds |

### Machine Learning

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Sentiment Analysis | vaderSentiment | 3.3.2 | Analyse de sentiment pour texte social media |
| NLP | textblob | 0.17.1 | Traitement du langage naturel |

### Message Queue

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| RabbitMQ Client | pika | 1.3.2 | Client AMQP pour RabbitMQ |

### Development Tools

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Linter | flake8 | 7.1.0 | Linting PEP 8 |
| Formatter | black | 24.8.0 | Formatting Python automatique |
| Testing | pytest | 8.3.3 | Framework de tests Python |

### File Upload

| Catégorie | Technologie | Version | Justification |
|-----------|-------------|---------|--------------|
| Multipart | python-multipart | 0.0.9 | Support de formulaire multipart |

### Architecture Pattern

**Type:** REST API / Service-oriented

**Caractéristiques:**
- API RESTful avec FastAPI
- Documentation auto-générée (Swagger/OpenAPI)
- Async/await pour performances
- Dependency injection
- Middleware pour auth, CORS
- Background tasks avec Celery/RabbitMQ

**Structure:**
- `app/api/` - Endpoints REST
- `app/models/` - Modèles SQLAlchemy
- `app/schemas/` - Schémas Pydantic
- `app/services/` - Business logic
- `app/ml/` - Services ML
- `app/scrapers/` - Scrapers (Twitter, Reddit, RSS)
- `app/queues/` - Gestion RabbitMQ
- `app/workers/` - Workers asynchrones
- `app/middleware/` - Middleware (auth, CORS)

---

## Architecture Globale

### Pattern de Communication

**Frontend ↔ Backend:**
- Protocol: REST API (HTTP/HTTPS)
- Format: JSON
- Base URL: `http://localhost:8000` (dev)

### Architecture de Données

**Phase 1 (Développement):**
- Frontend Database: SQLite (chartbastan.db)
- Backend Database: SQLite partagée
- ORM: Drizzle (frontend) + SQLAlchemy (backend)

**Phase 2+ (Production):**
- Database: PostgreSQL
- Cache: Redis (optionnel)
- ORM: Drizzle + SQLAlchemy

### Asynchronous Processing

**RabbitMQ:**
- Message broker pour tâches asynchrones
- Workers: scraping, analyse de sentiment, prédictions
- Découplage frontend/backend

---

## Dépendances Externes

### APIs Tierces

**Frontend:**
- Twitter API (accès direct, si configuré)
- Reddit API (accès direct, si configuré)

**Backend:**
- Twitter API v2 (via tweepy)
- Reddit API (via praw)

### Infrastructure

**Développement:**
- SQLite (base de données locale)
- RabbitMQ (optionnel, pour workers)

**Production (recommandé):**
- PostgreSQL (base de données)
- Redis (cache, sessions)
- RabbitMQ (message queue)
- VPS (hébergement)

---

## Sécurité

### Frontend
- better-auth pour authentification
- bcryptjs pour hashage des mots de passe
- Validation Zod des données d'entrée

### Backend
- Authentification JWT (via better-auth)
- Validation Pydantic
- CORS configuré
- Middleware de sécurité

---

## Performance

### Frontend Optimizations
- Next.js App Router (Server Components)
- Streaming et Suspense
- Code splitting automatique
- Optimisation d'images
- Cache React Query

### Backend Optimizations
- FastAPI async/await
- SQLAlchemy async operations
- Connection pooling
- RabbitMQ pour tâches lourdes

---

## Monitoring & Logging

### Frontend
- Logging via console (développement)
- Error tracking (à implémenter en production)

### Backend
- Logging structuré Python
- Error handling centralisé
- Monitoring (à implémenter en production)

---

## Testing

### Frontend Tests
- Vitest (framework de test)
- React Testing Library (composants)
- User Event (interactions)
- Type checking (TypeScript)

### Backend Tests
- pytest (framework de test)
- Tests unitaires et d'intégration
- Couverture de code (à implémenter)

---

## CI/CD

### Frontend
- ESLint
- TypeScript type-check
- Next.js build
- Tests Vitest

### Backend
- flake8 (linting)
- black (formatting)
- pytest (tests)

---

## Résumé de la Stack

**Frontend:**
- Framework: Next.js 16.1.3 + TypeScript 5
- UI: Tailwind CSS v4 + shadcn/ui
- State: Zustand + React Query
- Database: Drizzle ORM + SQLite
- Visualization: D3.js + Recharts

**Backend:**
- Framework: FastAPI 0.128.0 + Python 3.11+
- ORM: SQLAlchemy 2.0.45 + Alembic
- Scraping: tweepy + praw + feedparser
- ML: vaderSentiment + textblob
- Queue: RabbitMQ (pika)

**Infrastructure:**
- Database: SQLite (dev) → PostgreSQL (prod)
- Message Queue: RabbitMQ
- API Docs: Swagger/OpenAPI auto-généré

Cette stack est moderne, performante et bien adaptée aux besoins de l'application.