ISNAD — Domain Layer V1

Date : 2026-08-27
Statut : fondation
Objectif : introduire une couche src/domain/ sans casser l’existant, afin que les 5 prochaines années de développement s’appuient sur des entités et des contrats stables.

---

1. Vue d’ensemble#

L’architecture ISNAD adopte une structure en couches inspirée du Clean Architecture / Ports & Adapters :

---

2. Domain (src/domain/)#

Le domaine contient uniquement :

• entities/ — objets métier purs (Narrator, KnowledgeSource, KnowledgeEntry, Assertion, Evidence, Hadith, Chain, Commentary).
• repositories/ — interfaces de persistance (NarratorRepository, HadithRepository, KnowledgeRepository).
• services/ — interfaces de services métier (AnalysisService, NarratorService, HadithService).
• types/ — types transversaux (Decision, Confidence, EvidenceType).

Contraintes :

• Aucune dépendance vers Supabase, Next.js, React, scripts/.
• Aucune logique SQL.
• Les entités sont des objets de données typés, immutables par convention.

---

3. Infrastructure (src/infrastructure/)#

src/infrastructure/ est vide en V1. Il accueillera les adapters :

• supabase/NarratorRepositorySupabase.ts
• supabase/HadithRepositorySupabase.ts
• supabase/KnowledgeRepositorySupabase.ts
• quality-engine/QualityEngineRunner.ts
• search/SearchAdapter.ts

Règle d’or : la couche infrastructure ne contient que du mapping et du wiring. Toute logique métier reste dans src/domain/.

---

4. UI / Application#

La UI ne doit plus appeler directement supabase.from(...). À terme, les pages et composants consommeront :

• des server actions qui utilisent les services domaine,
• les repository adapters injectés par l’application.

En V1, aucune page n’est modifiée : la fondation est posée, le raccordement se fera dans une tâche ultérieure.

---

5. Quality Engine#

Le Quality Engine (scripts/quality-engine/) reste un framework indépendant. Il traite des entités techniques (alignements, passages, chaînes) et produit des Decision.

À terme, un adapter dans src/infrastructure/quality-engine/ permettra au domaine de déclencher des runs et de consommer leurs résultats sans connaître les détails du graphe de dépendances.

---

6. Knowledge Engine (futur)#

Le Knowledge Engine est le pipeline d’ingestion et de normalisation des sources savantes :

• transformer Taqrīb, Tahdhīb al-Kamāl, Mīzān, etc. en KnowledgeEntry,
• extraire des Assertion atomiques,
• les rattacher à des Evidence sourcés.

Il s’appuiera sur les entités src/domain/entities/ comme contrat de sortie.

---

7. Reasoning Engine (futur)#

Le Reasoning Engine répondra à la question :

« Le Prophète ﷺ a-t-il réellement dit cela ? »

Il consommera :

• les Assertion et Evidence du Knowledge Engine,
• les Chain et Hadith du corpus,
• les Decision du Quality Engine.

Il produira un argument scientifique structuré (hypothèses, preuves, contradictions, conclusion).

---

8. Schéma architectural#

Flèches :

• UI / Application dépend de Domain.
• Infrastructure implémente les interfaces de Domain.
• Engines consomment les adapters Infrastructure.
• Domain ne dépend de rien d’autre.

---

9. Règles de dépendance#

1. src/domain/ ne peut importer que depuis src/domain/.
2. src/infrastructure/ peut importer src/domain/.
3. src/app/ et src/components/ doivent passer par src/domain/ via des server actions.
4. scripts/quality-engine/ reste autonome mais produit des valeurs compatibles avec src/domain/types/Decision.ts.

---

10. Prochaines étapes#

1. Implémenter les adapters Supabase dans src/infrastructure/.
2. Créer des server actions qui injectent les adapters dans les services domaine.
3. Migrer progressivement les pages (narrators/[id], chain) pour utiliser les services domaine.
4. Implémenter le Knowledge Engine en sortie du modèle src/domain/entities/.
5. Construire le Reasoning Engine une fois que les assertions et les chaînes sont structurées.

---

V1 — fondation. Aucun comportement modifié, aucune page touchée.