Chatbot AI — Assistant Conversationnel Collaboratif

Application web de chatbot propulsée par Google Gemini API, avec un backend FastAPI et un frontend Vite + React + Tailwind CSS. Les conversations sont persistées dans une base PostgreSQL hébergée sur Neon.

Dépôt : github.com/Darul123-bit

---

Table des matières

• Aperçu
• Architecture
• Stack technique
• Structure du projet
• Prérequis
• Installation
• Variables d'environnement
• Lancement en local
• Déploiement
• API — Endpoints principaux
• Tests
• Contribuer
• Feuille de route
• Licence

---

Aperçu

Ce projet fournit une base réutilisable pour construire un chatbot IA prêt pour la production : gestion de l'historique des conversations, appels au modèle Gemini côté serveur (la clé API n'est jamais exposée au client), et une interface découplée du backend via une API REST documentée automatiquement par FastAPI (OpenAPI/Swagger).

Le choix d'une architecture frontend/backend séparée permet de déployer chaque partie indépendamment, de scaler le backend sans toucher au frontend, et de remplacer le moteur IA (Gemini, GPT, Claude...) sans impacter l'interface.

Architecture

┌────────────────────┐      HTTPS / REST      ┌──────────────────────┐      SQL      ┌───────────────┐
│  Frontend          │ ─────────────────────▶ │  Backend             │ ────────────▶ │  PostgreSQL   │
│  React 18 + Vite   │ ◀───────────────────── │  FastAPI + Uvicorn   │ ◀──────────── │  (Neon)       │
│  Cloudflare Pages  │        JSON            │  Render              │               └───────────────┘
└────────────────────                         └──────────┬───────────┘
                                                         │ appel API
                                                         ▼
                                              ┌────────────────────────┐
                                              │  Google Gemini API     │
                                              │  (Google AI Studio)    │
                                              └────────────────────────┘

Stack technique

Composant	Technologie	Rôle	Hébergement
Frontend	React 18, Vite, Tailwind CSS	Interface utilisateur, rendu et interactions	Cloudflare Pages
Backend	Python 3.11+, FastAPI, Uvicorn	Logique métier, appels à Gemini, exposition de l'API REST	Render
Base de données	PostgreSQL (Neon Serverless)	Persistance des conversations et de l'historique	Neon
Moteur IA	Google Gemini API (google-genai)	Génération des réponses conversationnelles	Google AI Studio

Structure du projet

chatbot/
├── backend/
│   ├── main.py               # Point d'entrée FastAPI (routes de l'API)
│   ├── database.py           # Connexion PostgreSQL (Neon) et modèle SQLAlchemy
│   ├── requirements.txt      # Dépendances Python
│   ├── .env.local            # Variables réelles (ignoré par git)
│   └── .env.example          # Modèle versionné, sans valeurs sensibles
│
├── frontend/
│   ├── src/
│   │   ├── App.jsx            # Point d'entrée React, monte ChatWindow
│   │   ├── components/
│   │   │   └── ChatWindow.jsx # Interface de chat (messages, saisie, envoi)
│   │   └── lib/
│   │       └── api.js         # Appels HTTP vers le backend FastAPI
│   ├── package.json          # Dépendances Node.js
│   ├── tailwind.config.js    # Configuration Tailwind CSS
│   ├── .env.local            # Variables réelles (ignoré par git)
│   └── .env.example          # Modèle versionné, sans valeurs sensibles
│
└── README.md

.env.local contient tes vraies valeurs et ne doit jamais être commité (Vite l'ignore par défaut, vérifie que .gitignore le liste aussi pour le backend). .env.example reste versionné comme référence pour quiconque installe le projet.

Prérequis

• Python 3.11+
• Node.js 18+ et npm
• Git
• Une clé API Gemini via Google AI Studio
• Un projet Neon pour la base PostgreSQL (offre gratuite disponible)

Installation

1. Cloner le dépôt

git clone https://github.com/Darul123-bit/chatbot.git
cd chatbot

2. Backend

cd backend
python -m venv venv
source venv/bin/activate      # Windows : venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env.local     # puis renseigner les vraies valeurs

3. Frontend

cd ../frontend
npm install
cp .env.example .env.local     # puis renseigner les vraies valeurs

4. Base de données

1. Créer un projet sur Neon.
2. Récupérer la chaîne de connexion (postgresql://user:password@host/dbname).
3. La renseigner dans DATABASE_URL (backend/.env).
4. Appliquer les migrations (Alembic ou script SQL selon l'implémentation retenue).

Variables d'environnement

Backend (backend/.env.local)

Variable	Description
GEMINI_API_KEY	Clé API Google Gemini
DATABASE_URL	Chaîne de connexion PostgreSQL (Neon)
CORS_ORIGINS	Origines autorisées à appeler l'API
ENV	development ou production

Frontend (frontend/.env.local)

Variable	Description
VITE_API_BASE_URL	URL du backend FastAPI (ex : http://localhost:8000)

Les fichiers .env.local ne doivent jamais être commités ; seuls les .env.example sont versionnés.

Lancement en local

Backend

cd backend
uvicorn main:app --reload --port 8000

API sur http://localhost:8000, documentation interactive sur http://localhost:8000/docs.

Frontend

cd frontend
npm run dev

Application sur http://localhost:5173.

Déploiement

Service	Plateforme	Configuration
Frontend	Cloudflare Pages	Build command : npm run build — dossier de sortie : dist
Backend	Render	Web Service Python — start command : uvicorn main:app --host 0.0.0.0 --port $PORT
Base de données	Neon	PostgreSQL serverless

Les variables d'environnement de production doivent être définies directement dans les dashboards Render et Cloudflare, indépendamment du fichier .env local.

API — Endpoints principaux

Méthode	Route	Description
POST	/chat	Envoie un message et retourne la réponse du modèle Gemini
GET	/conversations	Liste les conversations
GET	/conversations/{id}	Récupère l'historique d'une conversation
DELETE	/conversations/{id}	Supprime une conversation

À ajuster selon les routes réellement implémentées dans main.py.

Tests

# Backend
cd backend
pytest

# Frontend
cd frontend
npm run test

Contribuer

1. Fork le dépôt
2. Créer une branche (git checkout -b feature/ma-fonctionnalite)
3. Committer (git commit -m "feat: ajoute ma fonctionnalité")
4. Pousser la branche (git push origin feature/ma-fonctionnalite)
5. Ouvrir une Pull Request

Convention de commit recommandée : Conventional Commits. Documenter tout nouvel endpoint dans ce README.

Feuille de route

• Authentification utilisateur (JWT / OAuth)
• Streaming des réponses (Server-Sent Events)
• Support multi-modèles (Gemini, Claude, GPT)
• Export des conversations (PDF / Markdown)
• Mode hors-ligne / PWA

Licence

Projet sous licence MIT.