ISNAD Scientific Platform — Architecture V1

Statut : référence architecturale officielle
Date : 2026-09-13
Dernière mise à jour : clôture de E4 (identité des narrateurs), fondation de E5 (Tradition & Variant Graph), ajout de l'explorateur de base de données admin (BETA-01).
Périmètre : plateforme scientifique complète (pas seulement le Corpus Engine)
Durée de validité visée : 3 ans minimum
Fondations : docs/scientific/knowledge-model.md, docs/architecture/quality-engine-dependency-graph.md, docs/architecture/domain-layer.md

---

1. Vision globale#

1.1 Objectif final#

L’utilisateur demande : « Le Prophète ﷺ a-t-il réellement dit cela ? »

La plateforme produit une réponse scientifique argumentée, entièrement traçable, sourcée et révisable.

ISNAD Scientific Platform n’est plus une application de consultation. C’est un système de production de connaissance scientifique sur la transmission du hadith.

1.2 Principes directeurs#

1.3 Invariants d’architecture#

1. Le Narrator canonique ne porte aucune donnée savante.
2. Toute donnée savante est une Assertion rattachée à une KnowledgeEntry d’une KnowledgeSource.
3. Toute Assertion CANONICAL_CURRENT a au moins une Evidence SUPPORTS de type SOURCE_QUOTE.
4. Rien n’est écrasé : correction = nouvelle ligne + supersedes.
5. Les contradictions entre sources coexistent ; seule une décision datée et justifiée tranche.
6. Tout affichage est une projection calculée à partir d’assertions et de décisions.
7. Le raisonnement scientifique ne s’appuie jamais sur lui-même (anti-circularité).

---

2. Architecture générale#

La plateforme est découpée en 10 grands programmes (bounded contexts / systèmes). Chacun est autonome, versionné, et communique par des interfaces stables.

2.1 Les 10 programmes#

---

3. Description précise de chaque moteur#

3.1 Platform Foundation#

• Mission : gérer l’identité, les droits, l’audit, la configuration multi-tenant et le versionnement de la plateforme.
• Entrées : actions utilisateur, événements système, changements de configuration.
• Sorties : User, Tenant, Role, AuditLog, PlatformVersion.
• Interfaces : IdentityService, AuditService, ConfigService.
• Dépendances : aucune (c’est la base).
• Événements : USER_CREATED, USER_ROLE_CHANGED, CONFIG_UPDATED, AUDIT_LOG_WRITTEN.
• Versionnement : version sémantique de la plateforme (platform_version table).
• Qualité : logs append-only, RLS, authentification forte, traçabilité des actions administratives.

3.2 Corpus Engine#

• Mission : ingérer, normaliser et stocker les recueils de hadith (Boukhari, Muslim, etc.) avec leur hiérarchie collection → book → chapter → hadith → chain → chain_node.
• Entrées : fichiers sources (RDF, TXT, JSON, XML), métadonnées d’import.
• Sorties : Hadith, Chain, ChainNode, Collection, Book, Chapter.
• Interfaces : CorpusIngestionService, HadithRepository, ChainRepository.
• Dépendances : Search Engine (indexation), Quality Engine (validation), Rijal Engine (résolution des maillons).
• Événements : HADITH_IMPORTED, HADITH_MODIFIED, CHAIN_RESEGMENTED, IMPORT_BATCH_CREATED.
• Versionnement : processing_version par document, engine_version pour chaque sous-moteur (parser, normalizer).
• Qualité : hash du texte source, statut de structure (CLEAN_LINEAR, INCOMPLETE_CHAIN, etc.), traçabilité de l’import.

3.3 Rijal Engine#

• Mission : résoudre l’identité des narrateurs, gérer leurs formes de noms, leurs transmissions maître/élève, et construire leur profil scientifique.
• Entrées : mentions extraites de chaînes, sources de rijāl, feedback humain.
• Sorties : Narrator canonique, NameForm, NarratorTransmission, CrosswalkDecision, NarratorQualityProfile.
• Interfaces : NarratorResolutionService, NarratorRepository, NameFormRepository, TransmissionRepository.
• Dépendances : Corpus Engine (mentions), Search Engine (candidats), Knowledge Graph (assertions), Quality Engine (propagation).
• Événements : NARRATOR_MODIFIED, HUMAN_CORRECTION, NAME_FORM_CHANGED, TRANSMISSION_UPDATED.
• Versionnement : resolver_version, normalizer_version.
• Qualité : niveaux de confiance explicites (haute, moyenne, ambigue, non_resolue), feedback humain épingle les résolutions.
• Statut (E4, clôturé le 2026-09-12) : résolution d'identité de bout en bout (mention → représentation typée → candidat → preuve positive/négative → décision) livrée sur les chaînes Bukhārī + Muslim ; aucun classement par score, jamais de création automatique de Narrator, UNRESOLVED/AMBIGUOUS toujours préférés à un lien faux. Prochaine extension (S4.6C ou E5) hors périmètre de cette version.

3.4 Commentary Engine#

• Mission : ingérer des commentaires de hadith (Fatḥ al-Bārī, etc.), les segmenter en passages, les aligner aux hadiths, et extraire les assertions incidentes sur les narrateurs.
• Entrées : documents numérisés, éditions, manifestes.
• Sorties : commentary_document, commentary_passage, commentary_alignment, KnowledgeEntry légers, Assertion incidentes.
• Interfaces : CommentaryIngestionService, CommentaryAlignmentService, CommentaryAssertionExtractor.
• Dépendances : Corpus Engine (hadiths cibles), Search Engine (matn matching), Knowledge Graph (assertions), Quality Engine (règles validées).
• Événements : NEW_COMMENTARY, ALIGNMENT_VERIFIED, RULE_VALIDATED, NARRATOR_ASSERTION_EXTRACTED.
• Versionnement : processing_version, segmentation_version, alignment_version.
• Qualité : règles validées, preuve citée, statut de vérification humaine.

3.5 Search Engine#

• Mission : fournir la recherche floue et sémantique sur narrateurs, hadiths, chaînes et commentaires.
• Entrées : requêtes utilisateur, vecteurs, formes normalisées.
• Sorties : résultats classés avec score, tier, provenance.
• Interfaces : NarratorSearchService, HadithSearchService, CommentarySearchService.
• Dépendances : Corpus Engine, Rijal Engine, Commentary Engine, Search backend (Postgres/Elasticsearch/etc.).
• Événements : SEARCH_INDEX_UPDATED, RANKING_RULE_CHANGED.
• Versionnement : index_version, ranking_version.
• Qualité : golden tests, mesures de rappel/précision, gating par translittération.

3.6 Knowledge Graph Engine#

• Mission : assembler toutes les connaissances scientifiques en un graphe cohérent : sources, entrées, assertions, preuves, narrateurs, hadiths, chaînes.
• Entrées : sorties du Rijal Engine, du Commentary Engine, et futures ingestions de rijāl.
• Sorties : KnowledgeGraphView, NarratorDossier, HadithDossier, SourceGraph.
• Interfaces : KnowledgeGraphService, KnowledgeRepository, AssertionRepository, EvidenceRepository.
• Dépendances : Rijal Engine, Commentary Engine, Corpus Engine, Quality Engine (re-scans).
• Événements : ASSERTION_CREATED, EVIDENCE_LINKED, RECONCILIATION_DECISION_CREATED, KNOWLEDGE_SOURCE_ADDED.
• Versionnement : knowledge_model_version.
• Qualité : invariants du Knowledge Model, détection de conflits, traçabilité complète.

3.7 Reasoning Engine#

• Mission : raisonner scientifiquement sur les chaînes pour répondre à la question « Le Prophète ﷺ a-t-il réellement dit cela ? ».
• Entrées : Hadith, Chain, Assertion, Evidence, NarratorTransmission, règles de raisonnement.
• Sorties : ReasoningConclusion (hypothèses, preuves, contradictions, degré de certitude, recommandation).
• Interfaces : ChainReasoningService, IllaDetectionService, TuruqComparisonService.
• Dépendances : Knowledge Graph Engine, Corpus Engine, Rijal Engine.
• Événements : REASONING_REQUESTED, CONCLUSION_PRODUCED, ILLA_DETECTED, TURUQ_COMPARED.
• Versionnement : reasoning_rules_version, engine_version.
• Qualité : explicabilité obligatoire, anti-circularité, reproductibilité des conclusions.
• Statut (E5, ouvert) : fondation du Tradition & Variant Graph livrée (src/domain/tradition-variant/) — détection de candidats de tradition sur preuves convergentes (matn + Compagnon + isnād), jamais sur un seul signal ; domaine pur, sans persistance de groupes en base. STRONG_CANDIDATE signifie « mérite un regard humain », jamais « même tradition confirmée ». Périmètre actuel : Bukhārī + Muslim uniquement ; pas encore un moteur TuruqComparisonService complet.

3.8 Quality Engine#

• Mission : surveiller la qualité des données, propager les invalidations, tracer les décisions et empêcher les erreurs silencieuses.
• Entrées : événements métier, modifications de données, bumps de version moteur.
• Sorties : QualityDecision, QualityEngineState, DataQualitySnapshot.
• Interfaces : QualityEngine, EngineRegistry, DependencyGraph, InvalidationService.
• Dépendances : tous les autres moteurs (lecture seule).
• Événements : IMPORT_CORPUS, HADITH_MODIFIED, NARRATOR_MODIFIED, NEW_COMMENTARY, NEW_RULE, ENGINE_VERSION_BUMPED.
• Versionnement : engine_version par moteur, graph_version global.
• Qualité : hash gate, append-only, graphe acyclique, budget de recalcul, épingle humaine.

3.9 Administration#

• Mission : fournir les interfaces humaines de validation, de réconciliation, de gestion des règles et de supervision.
• Entrées : sorties des moteurs, actions de validateurs.
• Sorties : ReconciliationDecision, ValidatedRule, HumanFeedback, ReviewTask.
• Interfaces : AdminService, ReconciliationService, RuleValidationService.
• Dépendances : Quality Engine, Knowledge Graph Engine, Reasoning Engine.
• Événements : HUMAN_VERIFIED, RULE_PROMOTED, RECONCILIATION_DECIDED, FEEDBACK_APPROVED.
• Versionnement : version des règles validées.
• Qualité : audit complet, rôle reviewer, traçabilité des décisions humaines.
• Explorateur de base de données (BETA-01) : interface admin en lecture seule pour parcourir les tables de production sans accès direct au SQL ; usage interne de diagnostic, aucune écriture possible depuis l'UI.

3.10 API + Frontend#

• Mission : exposer les services aux utilisateurs et présenter les résultats de manière académique.
• Entrées : requêtes HTTP, actions utilisateur.
• Sorties : pages web, API JSON, exports scientifiques.
• Interfaces : REST/JSON API, React Server Actions, server components.
• Dépendances : tous les moteurs via les services domaine.
• Événements : USER_QUERY, PAGE_VIEW, EXPORT_REQUESTED.
• Versionnement : api_version.
• Qualité : affichage de la provenance, pas de score global trompeur, honnêteté des conclusions.

---

4. Relations entre les moteurs#

4.1 Flux de dépendances#

4.2 Graphe de dépendances du Quality Engine#

4.3 Flux d’un import complet#

---

5. Parcours d’une donnée#

5.1 Du texte brut à la réponse utilisateur#

5.2 Exemple concret : un hadith de Boukhari#

1. Import : le fichier RDF du recueil entre dans le Corpus Engine.
2. Parsing : le matn et l’isnād sont extraits → Hadith + Chain + ChainNode.
3. Résolution : chaque mention de la chaîne est envoyée au Rijal Engine.
4. Construction du narrateur : les mentions résolues créent ou mettent à jour des Narrator canoniques.
5. Enrichissement : les sources de rijāl (Taqrīb, Mīzān, etc.) produisent des KnowledgeEntry, des Assertion et des Evidence.
6. Alignement commentary : Commentary Engine aligne Fatḥ al-Bārī sur le hadith et extrait les assertions incidentes.
7. Assemblage : Knowledge Graph Engine relie narrateurs, chaînes, assertions, preuves.
8. Raisonnement : Reasoning Engine évalue la chaîne et produit une conclusion.
9. Affichage : le Frontend présente la conclusion avec sa provenance complète.

---

6. Interfaces entre moteurs#

6.1 Principes d’interface#

1. Contrat explicite : chaque moteur expose une interface stable (TypeScript + documentation).
2. Messages immuables : les entrées/sorties sont des objets de données, jamais modifiés en place.
3. Versionnement sémantique : chaque interface a une version (v1, v2, etc.).
4. Asynchrone : les interactions entre moteurs sont asynchrones (events / jobs / server actions).
5. Auditables : chaque échange entre moteurs est traçable (run ID, hash, timestamp).

6.2 Contrats principaux#

6.3 Transport#

• In-process : dans la même application Node.js/Next.js (server actions, services).
• Events : file de jobs pour les traitements lourds (ingestion, re-scans).
• API : REST/JSON pour les appels externes ou futurs services séparés.

---

7. Futures extensions#

7.1 Nouvelle collection de hadith#

1. Ajouter un plugin CorpusIngestion pour le format de la collection.
2. Produire des Hadith, Chain, ChainNode conformes au modèle.
3. Le Quality Engine propagera automatiquement les re-scans.
4. Le Search Engine réindexera.
5. Le Knowledge Graph et le Reasoning Engine fonctionneront sans modification.

7.2 Nouveau livre de rijāl#

1. Ajouter une KnowledgeSource.
2. Ajouter un plugin RijalSourceIngestion qui produit KnowledgeEntry + Assertion + Evidence.
3. Le Knowledge Graph Engine intègre les nouvelles assertions.
4. Le Reasoning Engine en tient compte automatiquement.

7.3 Nouveau commentaire#

1. Ajouter une KnowledgeSource de type HADITH_COMMENTARY.
2. Ajouter un plugin CommentaryIngestion pour le format (TXT, XML, etc.).
3. Réutiliser Commentary Engine : segmentation, alignement, extraction d’assertions.
4. Les alignements sont validés par Quality Engine et Administration.

7.4 Nouvelle langue#

1. Ajouter des traductions UI.
2. Ajouter des formes de noms translittérées dans NameForm.
3. Adapter le Search Engine (normalisation, phonétique).
4. Ajouter des KnowledgeEntry dans la nouvelle langue si disponible.

7.5 Nouveau moteur IA#

1. Définir un plugin Engine avec loadCandidates / evaluate / canonicalInputFields.
2. Enregistrer le moteur dans EngineRegistry.
3. Le Quality Engine l’ordonnance dans le graphe de dépendances.
4. Les décisions restent auditables et humainement révisables.

---

8. Bounded contexts (DDD)#

8.1 Frontières et responsabilités#

---

9. Risques d’architecture#

9.1 Dettes restantes#

9.2 Dépendances techniques#

9.3 Risques scientifiques#

---

10. Roadmap d’architecture#

Phase 1 : Fondations (0–6 mois)#

1. Stabiliser la reproductibilité (checksums, decision IDs, artifacts persistés).
2. Migrer vers le Knowledge Model V1 (KnowledgeEntry, Evidence, SourceEdition).
3. Implémenter les adapters Supabase dans src/infrastructure/.
4. Raccorder progressivement les pages aux services domaine.
5. Mettre en place CI/CD et tests automatisés.

Phase 2 : Moteurs (6–18 mois)#

6. Implémenter un deuxième moteur Quality Engine (Rijal resolver) pour valider le framework.
7. Construire le Knowledge Engine : ingestion générique des sources de rijāl.
8. Généraliser le Commentary Engine au-delà de Fatḥ.
9. Stabiliser Search Engine avec un modèle de recherche unifié.

Phase 3 : Raisonnement (18–36 mois)#

10. Modéliser les faits structurés pour le raisonnement (transmission, conditions, ṭuruq).
11. Construire le Reasoning Engine V0 sur un cas restreint.
12. Ajouter la détection d’ʿilal et la comparaison de ṭuruq.
13. Valider la chaîne scientifique complète sur un corpus de référence.

Phase 4 : Industrialisation (36+ mois)#

14. Architecture plugin pour nouvelles sources et moteurs IA.
15. Scalabilité : éventuel découpage en services indépendants.
16. API publique et exports scientifiques (PDF, RDF, TEI).
17. Communauté internationale : documentation en anglais, contribution externe.

Justification de l’ordre#

• Sans reproductibilité (Phase 1), toute décision scientifique est non vérifiable.
• Sans Knowledge Model (Phase 1), le raisonnement n’a pas de données structurées.
• Sans deux moteurs Quality Engine (Phase 2), le framework reste une hypothèse coûteuse.
• Sans faits structurés (Phase 3), le Reasoning Engine est impossible.
• Sans plugins (Phase 4), la plateforme ne deviendra jamais une référence mondiale extensible.

---

Annexes#

A. Glossaire#

B. Références internes#

• docs/scientific/knowledge-model.md
• docs/architecture/quality-engine-dependency-graph.md
• docs/architecture/domain-layer.md

---

V1 — référence architecturale officielle. Sera révisée à chaque évolution majeure de la plateforme.