Octobre 2022 : des PDFs cassés et des APIs mortes
Octobre 2022. Je veux analyser le Coran de manière analytique et structurée.
Je cherche un dataset propre. Je cherche une API fiable. Je cherche n’importe quel outil sérieux.
Je passe des heures à chercher. Résultat : zéro. Pas un seul outil digne de ce nom pour analyser le Coran comme un corpus linguistique.
Mon moment Eureka 💡
Je me suis posé la question :
- ✅ Je sais modéliser des données complexes
- ✅ Je sais construire des APIs en Python
- ✅ Je sais travailler avec des bases de données graphe
Si personne ne construit ça proprement, pourquoi ce quelqu’un ne serait pas moi ?
Le vide qui existait vraiment
Les outils Coran existants ont tous le même ADN. Ils sont conçus pour lire. Pas pour analyser. 🕳️
- Aucun ne propose les relations entre versets par racine arabe partagée
- Aucun ne traite le texte comme un corpus linguistique exploitable
- Aucun ne fournit une API REST moderne avec un graphe interrogeable
- Les datasets Kaggle existants : incomplets, mal nettoyés, sans structure relationnelle
- Zéro visualisation graphe. Zéro lien entre les 6 236 versets.
Ce n’est pas un manque d’intérêt. C’est un manque d’approche technique. Personne n’avait pensé à traiter le Coran comme un vrai dataset.
La décision : traiter le Coran comme un dataset
Février 2026. Je prends la décision : QuranicData.org.
L’objectif est clair dès le départ. Zéro interprétation religieuse. 100% data-driven. Un graphe vivant de relations entre versets, racines arabes et thèmes.
La relation clé qui change tout : SHARES_ROOT. Deux versets sont liés s’ils partagent une racine arabe commune. Personne ne proposait ça visuellement. Personne.
Stack technique
Backend : FastAPI Python 3.12 + SQLAlchemy + Pydantic — API REST typée et rapide
PostgreSQL 17 : Source de vérité absolue, ACID, maître de toutes les données
Neo4j 5.26 LTS : Moteur graphe, reconstruit depuis PostgreSQL, stocke les 6M+ relations
Infrastructure : VPS OVH Debian + Docker + Nginx Proxy Manager
PostgreSQL est le patron. Neo4j est reconstruit depuis PostgreSQL à chaque fois que nécessaire. Cette architecture évite toute désynchronisation.
Les défis techniques qui m’ont résisté
Ce projet avait des dents. Quatre problèmes concrets ont failli me bloquer. ⚔️
Défi #1 : 6 millions de relations et l’OOM Killer
La relation SHARES_ROOT représente 6 035 766 liens entre versets. Calculer ça d’un coup sur mon VPS OVH, c’est une opération brutale en RAM.
Sans configuration préalable, le processus d’import Neo4j se faisait tuer par l’OOM Killer du kernel Linux. Le processus mourait en silence. Pas d’erreur claire. Juste un process qui disparaissait.
- ✅ Diagnostic : surveillance des logs système et du comportement mémoire
- ✅ Solution : configurer 4 Go de swap sur le VPS avant de relancer l’import
- ✅ Résultat : import complet des 6M relations sans interruption
Défi #2 : L’encodage Buckwalter
Les racines arabes sont stockées en Buckwalter transliteration. C’est une convention technique standard en linguistique computationnelle arabe.
Problème : afficher « ktb » à l’utilisateur au lieu de « كتب » n’est pas acceptable. J’avais besoin d’un convertisseur Buckwalter → arabe.
- ✅ J’ai codé le convertisseur manuellement, sans librairie externe
- ✅ Chaque racine est stockée en Buckwalter (clé technique stable) et convertie à l’affichage
Défi #3 : 486 doublons dans le corpus morphologique
Lors du parsing du corpus morphologique source, j’ai détecté 486 doublons. Des occurrences de mots enregistrées deux fois avec des attributs légèrement différents.
- ✅ Mise en place d’une étape de déduplication pendant le parsing
- ✅ Validation croisée avec les chiffres attendus par sourate et par verset
Sans cette correction, les statistiques du graphe auraient été faussées dès la base.
Défi #4 : Le slash dans le mot de passe Docker
Problème inattendu et chronophage. Le mot de passe Neo4j contenait un caractère slash. Dans la chaîne de connexion Docker, ce caractère cassait silencieusement l’authentification.
- ✅ Diagnostic : tests d’authentification isolés hors Docker
- ✅ Solution définitive : utiliser uniquement des caractères hexadécimaux pour les mots de passe de services Docker
QuranicData.org aujourd’hui
Le site est en production. L’API est publique. Le graphe est vivant. 📊
📊 QuranicData.org en chiffres
La visualisation WebGL avec react-force-graph permet d’explorer le graphe des 6M relations en temps réel dans le navigateur. Aucun autre outil Coran ne propose ça.
Ce que j’ai appris
Trois leçons concrètes. Pas théoriques. 🧠
1. PostgreSQL d’abord, Neo4j ensuite
Utiliser PostgreSQL comme source de vérité et reconstruire Neo4j depuis PG est la bonne architecture. Tu ne perds jamais l’état de tes données.
2. Les problèmes d’infra arrivent toujours au mauvais moment
L’OOM Killer, le slash dans le mot de passe, les doublons du corpus — aucun n’était prévu. Un VPS configuré à moitié est une bombe à retardement.
3. Le différenciateur doit être technique, pas éditorial
N’importe qui peut faire un Quran viewer. La relation SHARES_ROOT sur 6M de paires de versets, personne ne l’avait construite. C’est ça qui rend le projet unique.
Aller plus loin
🎁 Explorer QuranicData.org
Visualise le graphe des 6 millions de relations. Interroge l’API. Explore les racines arabes.
Et après ?
Ce projet n’est pas terminé. Il est vivant.
- Ajouter les personnages et prophètes comme nœuds du graphe
- Implémenter les thèmes sémantiques avec des relations typées
- Mettre en place un pipeline CI/CD complet pour automatiser les déploiements
Un dataset propre sur le Coran existait dans ma tête en octobre 2022. Il existe sur internet aujourd’hui.