TREK

TREK - Plateforme de Partage de Ressources Pédagogiques

Théo de Romain Édouard pour Kento

Plateforme interne de JUNIA pour la gestion et le partage collaboratif de ressources pédagogiques entre enseignants.

---

📋 Table des matières

• Contexte du projet
• Fonctionnalités principales
• Architecture technique
• Prérequis
• Installation et démarrage
• Structure du projet
• Technologies utilisées
• Contribution

---

🎯 Contexte du projet

Problématique

JUNIA est une école d’ingénieurs regroupant de nombreux enseignants, incluant des enseignants-chercheurs internes et des intervenants externes. Actuellement, le partage des ressources pédagogiques entre enseignants présente plusieurs défis :

• Accès complexe : Lorsqu’un professeur reprend un cours, l’accès aux supports pédagogiques n’est pas toujours facile
• Absence de centralisation : Difficile de garantir l’alignement des cours avec le syllabus officiel
• Collaboration limitée : Manque d’outils pour faciliter le partage et la mise à jour collaborative des ressources

Solution

TREK est une plateforme centralisée permettant aux enseignants de :

• 📤 Partager leurs ressources pédagogiques (slides, documents, supports de cours)
• 🔄 Collaborer efficacement sur les contenus pédagogiques
• ✅ Garantir la cohérence et la qualité des enseignements
• 📚 Organiser les ressources par matières, modules et formations

---

✨ Fonctionnalités principales

📁 Gestion de documents

• ✅ Upload de fichiers multiples (PDF, DOCX, PPTX, XLSX, ODP, ODT)
• ✅ Validation automatique des fichiers (type MIME, taille, contenu)
• ✅ Gestion de versions avec historique complet
• ✅ Organisation hiérarchique (dossiers/sous-dossiers)
• ✅ Métadonnées enrichies (nom, commentaires, dates)

🔐 Sécurité des documents

• ✅ Watermarking automatique des PDFs avec texte diagonal
• ✅ Conversion Office → PDF avec watermark pour la distribution
• ✅ Téléchargement original réservé au personnel interne
• ✅ Authentification via Keycloak (SSO)
• ✅ Gestion des rôles (ADMIN, PROF_INTERNE, PROF_EXTERNE, ETUDIANT)

📄 Prévisualisation et conversion

• ✅ Aperçu PDF en ligne pour tous les documents
• ✅ Conversion asynchrone Office → PDF via Gotenberg
• ✅ Statuts de conversion (PENDING, PROCESSING, COMPLETED, FAILED)
• ✅ Download optimisé (PDF watermarké pour Green IT)

🗂️ Organisation

• ✅ Arborescence de dossiers personnalisable
• ✅ Types de dossiers (Cours, TP, TD, Projet, etc.)
• ✅ Archivage avec soft delete
• ✅ Recherche par nom de document

---

🏗️ Architecture technique

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                            │
│                  React 18 + TypeScript                      │
│                   Vite + TanStack Router                    │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP/REST
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                         Backend                             │
│              Spring Boot 3.5 + Java 17                      │
│        JPA/Hibernate + PostgreSQL + Flyway                  │
└────────┬─────────────────────────┬──────────────────────────┘
         │                         │
         │ Conversion              │ Auth/SSO
         ▼                         ▼
┌──────────────────┐      ┌──────────────────┐
│   Gotenberg      │      │    Keycloak      │
│  (Office → PDF)  │      │  (Auth + Roles)  │
└──────────────────┘      └──────────────────┘
         │
         │ Storage
         ▼
┌──────────────────┐
│   MinIO / S3     │
│  (Fichiers)      │
└──────────────────┘

Stack technique

• Frontend : React 18, TypeScript, Vite, TanStack Router, React Query
• Backend : Spring Boot 3.5, Java 17, Maven
• Base de données : PostgreSQL 18
• Authentification : Keycloak 26
• Conversion PDF : Gotenberg 8
• Watermarking : Apache PDFBox 3.0
• Conteneurisation : Docker/Podman + Compose
• CI/CD : GitHub Actions, Trivy (scan sécurité)

---

📦 Prérequis

Obligatoire

• Docker (≥ 24.0) ou Podman (≥ 4.0)
• Docker Compose ou Podman Compose
• Task (task runner) : Installation
• Git (≥ 2.30)

Recommandé pour le développement

• Node.js 20+ et npm 10+ (dev frontend local)
• Java 17 (dev backend local)
• Maven 3.9+ (dev backend local)

---

📂 Structure du projet

TREK/
├── backend/                  # Backend Spring Boot
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/com/junia/trek/backend/
│   │   │   │   ├── controller/     # API REST endpoints
│   │   │   │   ├── service/        # Logique métier
│   │   │   │   ├── repository/     # JPA repositories
│   │   │   │   ├── entity/         # Entités JPA
│   │   │   │   ├── dto/            # Data Transfer Objects
│   │   │   │   ├── mapper/         # Entity ↔ DTO mappers
│   │   │   │   ├── exception/      # Exceptions custom
│   │   │   │   └── config/         # Configuration Spring
│   │   │   └── resources/
│   │   │       ├── application.properties
│   │   │       └── db/migration/   # Scripts Flyway
│   │   └── test/
│   ├── Dockerfile
│   └── pom.xml
│
├── frontend/                 # Frontend React
│   ├── src/
│   │   ├── components/       # Composants React
│   │   ├── routes/           # Routes TanStack Router
│   │   ├── hooks/            # Custom hooks
│   │   ├── services/         # API clients
│   │   └── types/            # Types TypeScript
│   ├── Dockerfile
│   └── package.json
│
├── compose.yml               # Docker Compose configuration
├── Taskfile.yml              # Commandes task
├── .github/workflows/        # CI/CD GitHub Actions
├── doc/                      # Documentation
└── README.md

---

🛠️ Technologies utilisées

Backend

Technologie	Version	Usage
Spring Boot	3.5.6	Framework backend
Java	17	Langage
PostgreSQL	18	Base de données
Flyway	11.2	Migration de schéma
Apache PDFBox	3.0.3	Watermarking PDF
Apache Tika	3.2.3	Validation fichiers
SpringDoc OpenAPI	2.7.0	Documentation API (Swagger)
Keycloak	26.0.4	Authentification et gestion des rôles
Gotenberg	8	Conversion Office → PDF

Frontend

Technologie	Version	Usage
React	18.3	Framework UI
TypeScript	5.6	Langage
Vite	6.0	Build tool + dev server
TanStack Router	1.91	Routing
TanStack Query	5.62	State management + cache
Tailwind CSS	3.4	Styling

DevOps

Technologie	Version	Usage
Docker/Podman	Latest	Conteneurisation
GitHub Actions	-	CI/CD
Trivy	0.33	Scan de vulnérabilités
Husky	9.1	Git hooks
Commitlint	19.7	Validation des commits
lint-staged	15.3	Linting pré-commit
Task	3.x	Task runner

---

🤝 Contribution

Workflow Git

1. Créer une branche depuis main :

   git checkout main
   git pull
   git checkout -b feat/ma-fonctionnalite
   

2. Commits conventionnels (obligatoire) :

   git commit -m "feat: ajouter la fonctionnalité X"
   git commit -m "fix: corriger le bug Y"
   git commit -m "docs: mettre à jour le README"
   

   Types autorisés : feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert

3. Push et Pull Request :

   git push origin feat/ma-fonctionnalite
   # Créer une PR sur GitHub
   

4. Review et merge : Attendre l’approbation et les checks CI/CD avant merge

Standards de code

• Backend : Google Java Style Guide (via Checkstyle)
• Frontend : ESLint + Prettier
• Commits : Conventional Commits (via Commitlint)
• Hooks : Pre-commit linting automatique (Husky + lint-staged)

Pour plus de détails, voir CONTRIBUTING.md

---

📄 Licence et équipe

Projet académique - JUNIA (Hauts-de-France School of Engineering)

Développé par des étudiants en 3ème année cycle ingénieur dans le cadre d’un projet de semestre.

---

📞 Support

Pour toute question ou problème :

1. Consulter la documentation
2. Contacter l’équipe de développement

---

Fait avec ❤️ par l’équipe TREK