edbuild-ai

EdBuild-AI est une API de transformation pédagogique qui prend un document en entrée et génère automatiquement des segments (notions), des synthèses sémantiques, des activités interactives et des slides, le tout orchestré de bout en bout.

🚀 Fonctionnalités

• 🚀 Pipeline Document complet
  Orchestration unique (POST /api/document) pour importer un document, le numériser, le segmenter en "notions", analyser chaque segment, générer activités et slides puis persister les résultats.

• 📄 Numérisation avancée
  Conversion de documents en format JSON structuré avec extraction précise du texte, des images et des tableaux via OCR.

• 🤖 Analyse sémantique avancée
  Extraction de synthèses pédagogiques, concepts clés, tableaux et formules via GPT pour chaque notion extraite.

• 📊 Génération d'activités variées
  Création de QCM/QCU, glossaire, flashcards, textes à trou et exercices glisser–déposer paramétrables (niveau, nombre, type).

• 💾 Historique & persistance
  Sauvegarde des versions originales (sur un cache de 3j) et enrichies de chaque segment avec un job_id unique pour un suivi et un audit complets.

• 🔄 Export & intégration
  Export des contenus formatés et des slides en JSON, HTML ou Markdown, déployable en conteneur Docker pour intégration continue.

• 🧪 Qualité et tests
  Couverture unitaire ≥ 80 %, configuration ESLint/Prettier/Husky, lint-staged, commitlint prête à l'emploi pour garantir la robustesse.

🛠 Stack Technique

• API:
  • Express 5
  • TypeScript
  • OpenAPI
• Tests:
  • Jest
• Documentation: Swagger UI Express
• Conteneurisation: Docker
• Qualité de Code:
  • ESLint
  • Prettier
  • Husky
  • lint-staged
  • conventional-changelog
• Logging & Monitoring:
  • Morgan (HTTP request logging)
  • Pino (JSON logging)
• Security & Performance:
  • Express Rate Limit (API rate limiting)
  • Helmet (Security headers)
  • Compression (Response compression)
  • CORS (Cross-Origin Resource Sharing)
• Validation & Type Safety:
  • Zod (Runtime type checking)
  • TypeScript strict mode
• Error Handling:
  • Express error middleware
  • Custom error classes
  • Global error handler

📦 Installation

# Cloner le repository
git clone [git-url]

# Installer les dépendances
pnpm install

# Initialiser Husky
pnpm run prepare

# Lancer le serveur de dev
pnpm run dev

🔧 Configuration

Variables d'environnement

• Voir le fichier .env.sample for

Commandes disponibles

# Développement
pnpm run dev:        # Lancer le serveur de développement
pnpm run build       # Build pour la production
pnpm run start       # Pour start la production

# Qualité de Code
pnpm run lint:fix    # Corriger automatiquement les problèmes de linting
pnpm run format      # Formater le code avec Prettier
pnpm run test        # Lancer les tests

# Versioning
pnpm run release     # Créer une nouvelle version
pnpm run changelog   # Mettre à jour le CHANGELOG

Docker

# Construire les images
docker-compose build

# Lancer les services
docker-compose up -d

📝 Conventions de Code

Outils de Qualité de Code

Le projet utilise plusieurs outils pour maintenir la qualité du code :

• ESLint : Analyse statique du code
• Prettier : Formatage automatique du code
• Husky : Hooks Git pour automatiser les vérifications
• lint-staged : Exécution des linters sur les fichiers modifiés
• conventional-changelog : Génération automatique du CHANGELOG

Vérifications Automatiques

• Pre-commit :

  • Vérification du linting
  • Formatage du code
  • Vérification des types TypeScript

• Pre-push :

  • Exécution des tests
  • Mise à jour du CHANGELOG

Gestion des Commits

Le projet utilise Husky et commitlint pour assurer la qualité et la cohérence des messages de commit.

Configuration des Commits

• Husky : Gère les hooks Git pour valider les commits
• commitlint : Vérifie que les messages de commit suivent les conventions

Types de Commits Autorisés

• feat: Nouvelle fonctionnalité
• fix: Correction de bug
• docs: Documentation
• style: Formatage, point-virgules manquants, etc.
• refactor: Refactorisation du code
• perf: Amélioration des performances
• test: Ajout ou modification de tests
• chore: Maintenance, dépendances, etc.
• revert: Annulation d'un commit
• ci: Configuration CI/CD
• build: Build system ou dépendances externes

Règles de Validation

• Le type doit être en minuscules
• Le scope est optionnel et doit être en minuscules
• La description doit être en minuscules
• Pas de point final dans la description
• Longueur maximale du header : 72 caractères

Exemples de Commits Valides

feat: ajouter le support des fichiers markdown
fix(parser): corriger le parsing des liens
docs(readme): mettre à jour la documentation d'installation
style: formatter le code selon les standards

Versioning Sémantique

Le projet suit le versioning sémantique (SemVer - MAJOR.MINOR.PATCH).

🧪 Tests

Les tests sont configurés avec Jest.

pnpm run test

🔄 Workflow Git

• main: Branche de production
• develop: Branche de développement
• Les fonctionnalités sont développées dans des branches feature/
• Les corrections de bugs dans des branches fix/

🏗 Structure du Projet

edbuild-ai/
├── api/ # Code source principal
│ ├── config/ # Configuration (env, logger, swagger…)
│ ├── controllers/ # Handlers HTTP (document, slides, notions, activities, health…)
│ ├── middlewares/ # Auth, validation, error-handler…
│ ├── models/ # (vide ou à compléter)
│ ├── routes/ # Déclaration des routes et montage des controllers
│ ├── services/ # Logique métier / appels aux microservices
│ │ ├── orchestrator/
│ │ ├── slides/
│ │ ├── notions/
│ │ ├── activities/
│ │ ├── openai/
│ │ └── document-scanner/
│ ├── types/ # Types et interfaces partagés
│ │ ├── services/
│ │ └── shared/
│ ├── utils/ # Fonctions utilitaires (cache, notion, prompts…)
│ │ ├── cache/
│ │ ├── notion/
│ │ └── prompts/
│ ├── index.ts # Point d'entrée (Express app)
│ └── server.ts # Lancement du serveur
│
├── test/ # Tests automatisés (unitaires et d'intégration)
│ ├── slides/
│ ├── cache/
│ ├── activities/
│ ├── openai/
│ ├── swagger/
│ ├── notions/
│ ├── mocks/
│ ├── document/
│ └── index.test.ts
│
├── docs/ # Documentation et diagrammes
│ ├── swagger/
│ │ └── v1/
│ │ ├── openapi.yaml
│ │ ├── paths/
│ │ └── components/
│ ├── diagram/
│ ├── pdf-examples/
│ └── GLOSSARY.md
│
├── .husky/ # Hooks Git (pre-commit, commit-msg…)
├── .github/
│ └── workflows/ # CI/CD (GitHub Actions)
├── .cache/ # Cache local (dev)
├── dist/ # Build de l'API (output)
├── node_modules/
│
├── Dockerfile # Build de l'API
├── docker-compose.yml # Orchestration (si services externes)
├── docker-compose.local.yml
├── .dockerignore
│
├── .eslintrc.js # ESLint config
├── .prettierrc # Prettier config
├── .prettierignore
├── commitlint.config.js # Commitlint config
├── .versionrc # Standard-version config
├── jest.config.cjs # Jest config
├── tsconfig.json # TypeScript config
├── package.json # Dépendances & scripts
├── pnpm-lock.yaml
├── CHANGELOG.md
└── README.md # Présentation & instructions

🗂️ Aperçu rapide des endpoints de l'API

/api
├── document
│   └── POST /api/document       # Lance l'intégralité du pipeline (Document Orchestrator)
│   └── GET /api/document # Vérifie le statut d'un job
│   └── GET /api/document/result # Récupère le résultat d'un job
/documentScanner
│   └── POST /api/documentScanner      # Convertit un PDF en JSON
/notions
│   └── POST /api/notions        # Segmentation du PDF en "notions" (segments)
/activities
│   └── POST /api/activities/generate   # Génère les activités au format JSON/HTML/Markdown
│   ├── POST /api/activities/unique-choice   # Génère un QCU
│   ├── POST /api/activities/multiple-choice # Génère un QCM
│   ├── POST /api/activities/glossary        # Génère un glossaire de termes
│   ├── POST /api/activities/flashcards      # Génère des flashcards
│   ├── POST /api/activities/fill-in         # Génère des phrases à trous
│   └── POST /api/activities/drag-drop       # Génère un glisser–déposer
/slides
│   └── POST /api/slides   # Génère les slides au format JSON/HTML/Markdown
/health
└── GET  /api/health                # Vérifie le statut de l'API et de ses dépendances

📝 Modélisation du statemachine

stateDiagram-v2
    [*] --> pending
    pending --> parsing

    parsing --> notion

    notion --> activities

    activities --> slides

    slides --> completed
    slides --> failed

    %% Error transitions
    parsing --> failed
    notion --> failed
    activities --> failed

Bon à savoir

Configuration de l'API

• Vous pouvez activer ou désactiver l'évaluation de la qualité des documents en définissant « enable_quality_score » dans l'objet de configuration lors de l'appel de l'API de traitement des documents. Exemple : « { "enable_quality_score": false } » désactive l'évaluation de la qualité et les commentaires.

Alertes de qualité et de dépassement de délai

• Si l'évaluation de la qualité du document est inférieure à 75, une alerte est envoyée aux administrateurs (Discord/Slack) et l'utilisateur reçoit un message d'erreur clair : « La qualité du document généré est trop faible. Veuillez vérifier votre saisie ou essayer un autre fichier.» (sauf si l'évaluation de la qualité est désactivée).
• Si le temps de génération du document (dans documentScanner) dépasse « GENERATION_TIME_LIMIT » (par défaut : 300 secondes), une alerte est envoyée aux administrateurs et l'utilisateur reçoit le message suivant : « La génération du document a pris trop de temps. Veuillez réessayer ultérieurement ou utiliser un fichier plus petit. » - Les alertes sont envoyées via les webhooks Discord et Slack configurés (voir les variables d'environnement « DISCORD_WEBHOOK_URL » et « SLACK_WEBHOOK_URL »).

Gestion des téléchargements de fichiers

L'application gère les téléchargements de fichiers différemment selon l'environnement de développement ou de production :

• Développement : Utilise les noms de fichiers d'origine pour faciliter le débogage et l'identification du cache.
• Production : Utilise des noms de fichiers basés sur des UUID pour prévenir les attaques par traversée de chemin et les vulnérabilités par injection.

Ce comportement est automatiquement géré par le middleware de téléchargement, basé sur la variable d'environnement « NODE_ENV ».

Environnement de test Railway

L'environnement de test Railway est déployé comme une application sans serveur qui peut se mettre en veille après une période d'inactivité. Dans ce cas, la première requête peut recevoir une erreur 502 avec le message « Échec de la réponse de l'application » :

Pour réactiver l'application, réessayez simplement. L'application sera prête à traiter les requêtes après une courte période de préchauffage.