chartbastan/docs/technology-stack.md

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.