🎓 Documentation Technique - Gestionnaire de Projets et Groupes Étudiants

Plateforme web complète pour la gestion collaborative de projets étudiants avec intégration GitHub

🚀 Démo en Ligne

Pour une démonstration de l'application, rendez-vous sur : samvs17.com

💡 Important : Pour voir la pleine fonctionnalité du projet, il est recommandé d'utiliser la démo en ligne sur samvs17.com car elle dispose de tous les fichiers de configuration nécessaires.

📋 Vue d'ensemble du projet

Cette application web permet aux enseignants de créer des projets et aux étudiants de s'organiser en groupes de travail de manière autonome. Le système offre une gestion complète des projets académiques avec une intégration GitHub pour le suivi du code source.

🏗️ Architecture Technique

Frontend (`/frontend`)

Framework : React 19 avec TypeScript
Build Tool : Vite 7.1.7 pour un développement rapide
Styling : SCSS avec modules CSS
State Management : Context API React
HTTP Client : Axios pour les requêtes API
Routing : React Router DOM v7

Backend (`/backend`)

Runtime : Node.js (compatible avec Node 22.21+)
Framework : Express.js v5
ORM : TypeORM 0.3.27 pour la gestion base de données
Base de données : MariaDB sur serveur distant avec mysql2
Authentification : JWT + Système de tokens cryptés (AES-256)
API : RESTful avec gestion d'erreurs centralisée
Sécurité : Helmet, CORS, Rate Limiting, bcrypt

⚙️ Prérequis Système

Node.js : Version 22.21 minimum
MariaDB : Accès à un serveur MariaDB distant (configuré par l'administrateur)
Git : Pour le clonage du repository
npm : Gestionnaire de paquets (inclus avec Node.js)

🛠️ Installation

1. Clonage du Repository

git clone <votre-repository-url>
cd projetweb3

2. Installation des Dépendances Backend

cd backend
npm install

3. Installation des Dépendances Frontend

cd ../frontend
npm install

🔧 Configuration

Variables d'Environnement

Créer le fichier backend/src/creds.env avec les variables suivantes :

# Configuration Base de Données (serveur distant)
DB_HOST=your_database_host
DB_PORT=3306
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_NAME=your_database_name

# URL Frontend (pour CORS)
FRONT_URL=http://localhost:5173

# Clés de Sécurité
CRYPTO_SECRET_KEY=your_32_character_secret_key_for_encryption
JWT_SECRET=your_jwt_secret_key_for_tokens

⚠️ Important : Pour des raisons de sécurité, le fichier creds.env contenant les vraies valeurs n'est pas fourni dans le repository. Il doit être configuré par l'administrateur système lors du déploiement.

🔴 ATTENTION : Le projet ne fonctionnera pas sans le fichier creds.env correctement configuré. Sans ce fichier, l'application ne pourra pas se connecter à la base de données MariaDB distante ni utiliser les clés de sécurité nécessaires. Pour voir le projet en action avec toutes ses fonctionnalités, consultez la démo en ligne sur samvs17.com.

L'application utilise TypeORM avec synchronize: true, les tables seront créées automatiquement au démarrage sur le serveur MariaDB distant.
Le seeding automatique s'exécute au démarrage pour initialiser les données de base.

🚀 Démarrage en Développement

⚠️ Prérequis obligatoire : Avant de démarrer l'application, assurez-vous d'avoir configuré le fichier backend/src/creds.env avec les bonnes valeurs. Sans ce fichier, l'application ne démarrera pas.

Démarrage du Backend

cd backend
npm start

Le serveur backend sera accessible sur http://localhost:3000

Démarrage du Frontend

cd frontend
npm run dev

L'application frontend sera accessible sur http://localhost:5173

🔥 Démarrage en Production

Build et Démarrage du Backend

cd backend
npm run build
npm start

Build du Frontend

cd frontend
npm run build

Les fichiers de production seront générés dans frontend/dist/

🌐 Déploiement avec Jenkins

Le projet inclut un Jenkinsfile pour l'intégration continue avec les étapes suivantes :

Pull du code depuis le repository Git
Installation des dépendances backend et frontend
Build des applications
Redémarrage des services système

Services Système Requis

Le déploiement automatique nécessite la configuration des services systemd :

Service Backend (`/etc/systemd/system/groupe10-backend.service`)

[Unit]
Description=Groupe10 Backend API
After=network.target mysql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/Groupe10/backend
ExecStart=/usr/bin/node build/server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Commandes de Gestion des Services

# Activer et démarrer le service
sudo systemctl enable groupe10-backend.service
sudo systemctl start groupe10-backend.service

# Vérifier le statut
sudo systemctl status groupe10-backend.service

# Redémarrer le service
sudo systemctl restart groupe10-backend.service

Configuration Apache

Pour servir le frontend, configurer le serveur web pour servir les fichiers statiques depuis frontend/dist/ et rediriger les requêtes API vers http://localhost:3000.

🔒 Sécurité

Authentification et Autorisation

JWT Tokens pour l'authentification des utilisateurs
Tokens cryptés AES-256 pour la sécurité des données sensibles
bcrypt pour le hachage des mots de passe
Rate Limiting pour prévenir les attaques par déni de service

Configuration CORS

Le backend accepte uniquement les requêtes depuis l'URL définie dans FRONT_URL.

Middleware de Sécurité

Helmet pour sécuriser les en-têtes HTTP
Validation des données avec Joi et Yup
Gestion centralisée des erreurs

📊 Endpoints API Principaux

Santé de l'Application

GET /api/health - Vérification de l'état du serveur

Gestion des Utilisateurs

POST /api/user/login - Connexion

Gestion des Projets

GET /api/projects - Liste des projets
POST /api/projects - Création d'un projet
GET /api/projects/:id - Détails d'un projet

Gestion des Groupes

GET /api/groups/public/:publicToken/groups - Groupes par token public
POST /api/groups/project/:projectId/groups - Créer un groupe
POST /api/groups/project/:projectId/groups/:groupId/join - Rejoindre un groupe

Intégration GitHub

POST /projects/:projectId/add-members - Ajouter membres au repository
GET /user/:userId/organization - Liste des organizations de l'admin (grâce au token GitHub)
GET /user/:userId/organization/:orgName - Informations de l'organization

🗄️ Structure de la Base de Données

Entités Principales

User - Utilisateurs (enseignants)
Project - Projets créés par les enseignants
Group - Groupes de travail
GroupMember - Membres des groupes (relation many-to-many)

Relations

Un Projet peut avoir plusieurs Groupes
Un Groupe peut avoir plusieurs Membres
Un Utilisateur peut être membre de plusieurs Groupes, mais un seul groupe par projet

🔧 Processus en Arrière-Plan

Seeding Automatique

Au démarrage du serveur, le système exécute automatiquement :

userSeeder.ts - Création des utilisateurs par défaut
databaseSeeder.ts - Initialisation des données de base

Création d'Utilisateurs

Pour ajouter un nouvel utilisateur (enseignant) au système, vous devez modifier le fichier backend/src/seeds/userSeeder.ts :

Localiser le tableau users dans le fichier userSeeder.ts
Ajouter les informations utilisateur au format suivant :

const users = [
    { 
        userName: 'nom-utilisateur', 
        password: 'mot-de-passe-en-clair', 
        token: 'token-github-personnel' 
    }
];

Redémarrer l'application pour que le seeding s'exécute
Important : Effacer les données du tableau après le premier démarrage pour des raisons de sécurité

⚠️ Sécurité : Ne laissez jamais de mots de passe ou tokens en clair dans le code après le seeding initial. Le système chiffre automatiquement les mots de passe avec bcrypt et les tokens avec AES-256.

💡 Token GitHub : Le token GitHub doit avoir les permissions nécessaires pour créer des repositories et gérer des collaborateurs dans l'organisation cible.

Synchronisation GitHub

Les opérations GitHub (création de repositories, gestion des collaborateurs) sont exécutées de manière asynchrone via l'API Octokit.

Pas de Crontab Requis

L'application ne nécessite pas de tâches cron spécifiques. Toutes les opérations sont déclenchées par les interactions utilisateur ou les événements système.

🐛 Dépannage

Problèmes Courants

Erreur de Connexion à la Base de Données
- Cause principale : Fichier creds.env manquant ou mal configuré
- Vérifier les variables d'environnement dans creds.env
- S'assurer que le serveur MariaDB distant est accessible
- Vérifier les permissions de l'utilisateur MariaDB et la connectivité réseau
- Solution recommandée : Utilisez la démo en ligne sur samvs17.com pour voir le projet fonctionner
Erreur CORS
- Vérifier que FRONT_URL correspond à l'URL du frontend
- Contrôler la configuration CORS dans server.ts
Erreurs de Build
- S'assurer d'utiliser Node.js 22.21+
- Nettoyer les node_modules et réinstaller : rm -rf node_modules && npm install

Logs et Monitoring

# Logs du service backend
sudo journalctl -u groupe10-backend.service -f

👥 Support et Maintenance

Démo Live : samvs17.com ← Utilisez cette démo pour voir toutes les fonctionnalités
Node.js Version : 22.21+ requis
Configuration requise : Fichier creds.env obligatoire pour le fonctionnement local
Déploiement : Automatisé via Jenkins
Monitoring : Logs systemd et journalctl

Lien de la vidéo

La vidéo youtube du projet : Vidéo

🎯 Projet académique HELHa 2025-2026 - Architecture full-stack TypeScript avec intégration GitHub et déploiement automatisé.

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
frontend		frontend
.gitignore		.gitignore
Jenkinsfile		Jenkinsfile

Latest commit

History

Folders and files

Repository files navigation