sasedev-knowledge/docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md

Architecture de fondation Knowledge

Décision structurante

Knowledge part d'un monolithe modulaire. Les frontières décrites ici sont des responsabilités et ports logiques, pas une obligation de créer un service ou une crate par boîte.

Le principe directeur est :

Git est le backend du contenu ; une forge est une capacité optionnelle.

Vue de responsabilités

HTTP / SSR / admin
        |
        v
application use cases
        |
        +---------------------> content/domain contracts
        |                              |
        |                              +---- parsing / validation
        |                              +---- proposal / review rules
        |                              +---- publication selection
        |
        +---- GitRepository ----------> Git local / remote générique
        |
        +---- GitForge ---------------> Gitea ou autre forge, optionnel
        |
        +---- RepositoryEventSource --> sync explicite / polling / hook / webhook
        |
        +---- application state ------> PostgreSQL
        |
        +---- local index/cache ------> lecture publique / recherche / rendu

La dépendance pointe vers les contrats métier. Les détails Actix, processus Git, API Gitea ou SQL ne remontent pas dans le domaine.

1. Application et domaine

Le domaine porte les concepts durables : source de contenu, révision, proposition, validation, publication, type documentaire et références entre contenus.

La couche application orchestre les cas d'usage tels que synchroniser un dépôt, indexer une révision, ouvrir/revoir une proposition et publier une révision autorisée.

Les modèles HTTP, SQL et payloads Gitea ne sont pas des modèles domaine par défaut.

2. Git générique

Le contrat conceptuel GitRepository couvre uniquement les opérations Git nécessaires :

refs / resolve revision
fetch
checkout ou worktree local
status/diff
branch
commit
merge/rebase contrôlé lorsque le workflow l'exige
push lorsque autorisé

L'implémentation doit fonctionner sans connaître Gitea, GitHub ou GitLab.

Le serveur préfère des mirrors/clones et worktrees locaux. Une requête publique ne doit pas déclencher un appel réseau vers la forge.

3. Forge optionnelle

Le contrat conceptuel GitForge porte uniquement les capacités qui ne sont pas des opérations Git fondamentales :

pull/merge requests
issues
permissions forge
releases forge
webhooks et métadonnées spécifiques

L'absence d'un adapter forge ne doit pas empêcher la synchronisation d'un dépôt local/générique, la lecture publique ou le workflow interne de proposition.

Gitea est le premier candidat d'intégration mais n'est pas figé comme dépendance du domaine.

4. Événements et synchronisation

Le contrat conceptuel RepositoryEventSource produit un signal de synchronisation, pas une vérité de contenu.

Sources prévues :

sync explicite
polling
hook Git local/serveur
webhook de forge
watcher filesystem éventuel

Toutes convergent vers le même cas d'usage interne :

signal
  -> fetch/refresh si nécessaire
  -> résolution de la révision cible Git
  -> comparaison avec la dernière révision indexée
  -> checkout/worktree de la révision
  -> parsing + validation
  -> construction d'une projection/index
  -> publication atomique de l'état dérivé

Un webhook peut être perdu ou dupliqué. Le commit Git résolu reste l'identité autoritaire de la révision.

5. Propositions et revues

Le workflow exact reste à formaliser avant implémentation, mais le contrat minimal conserve :

auteur
cible
révision Git de base
patch ou contenu proposé
statut
historique de revue
résultat de validation
révision/branche résultante si acceptée

Une proposition ne modifie jamais directement la révision publiée.

Si la base n'est plus courante, le workflow doit pouvoir signaler un conflit/rebase plutôt que forcer un écrasement.

Une pull request de forge MAY refléter ou accélérer ce workflow ; elle n'en est pas le modèle autoritaire obligatoire.

6. Parsing et validation des contenus

Le contrat conceptuel ContentRepository expose du contenu normalisé au métier sans révéler le provider Git ou forge.

Le format final des HOWTOs/snippets reste DEFER. Le parseur devra néanmoins pouvoir produire au minimum :

identité logique
famille de contenu
révision source
métadonnées normalisées
corps rendu/parsé
références sortantes
résultat de validation

Les validations normatives PGR restent propres au corpus PGR. Knowledge ne doit pas inventer une règle PGR pour simplifier son parseur.

7. Index, recherche et cache

L'index/cache est une projection reconstructible du contenu Git.

PostgreSQL MAY contenir des documents/index/métadonnées dérivés et assurer une première capacité de recherche. Aucun moteur de recherche externe n'est sélectionné en 0.0.1.

Une projection doit garder la révision Git source afin de savoir exactement quel contenu elle représente.

8. Rendu et publication

La publication sélectionne une révision autorisée, la valide/indexe puis la rend disponible localement.

Pour PGR :

• le canal stable provient d'un tag stable vérifié par le workflow PGR ;
• un canal dev MAY exister mais doit être visuellement et sémantiquement distinct.

Pour HOWTOs/snippets :

• la cadence MAY être continue et plus légère ;
• le workflow SemVer/delta/history PGR n'est pas imposé artificiellement.

Actix Web et Maud sont des choix de composition/rendu locaux. Vite gère les assets/interactions frontend lorsqu'il est matérialisé.

9. Administration

L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité.

Elle pourra gérer propositions, revues, synchronisation, validation et publication. Une UI complète est hors scope 0.0.1.

10. Authentification et autorisation

Le domaine doit distinguer identité, rôle/capacité et action autorisée, mais le fournisseur d'identité et le mécanisme complet restent différés.

Les permissions forge ne sont pas supposées équivalentes aux permissions applicatives.

11. Frontières PGR / HOWTO / snippet / project-local

Les quatre familles gardent une sémantique propre :

Famille	Rôle	Force
PGR	règle/contrat de gouvernance	normative dans son scope
HOWTO	procédure, diagnostic, explication, anti-pattern	guidance
snippet	exemple court, commande, configuration, fragment	contextualisée
project-local	décision concrètement instanciée	locale au projet

Les métadonnées peuvent relier ces familles sans promotion automatique de force normative.

Une pratique répétée dans HOWTO/snippet peut devenir un candidat d'étude PGR ; elle n'est normative qu'après le workflow PGR correspondant.

12. Git versus PostgreSQL

Autoritaire dans Git

• corps du contenu publié ;
• métadonnées éditoriales versionnées avec ce contenu ;
• historique de révisions Git ;
• refs/tags/branches autorisées par la politique de chaque dépôt.

État applicatif PostgreSQL

• utilisateurs/sessions ;
• propositions et revue ;
• commentaires/audit applicatif ;
• configuration logique des sources ;
• dernière révision synchronisée/indexée ;
• index et recherche dérivés ;
• relations calculées ;
• jobs de synchronisation/publication ;
• cache/projections reconstructibles.

Interdit comme raccourci architectural

Une modification du contenu publié ne doit pas exister uniquement dans PostgreSQL après acceptation. L'acceptation doit produire une révision Git avant qu'elle devienne contenu publié.

Topologie de dépôts retenue

sasedev-knowledge  application et gouvernance de la plateforme
pgr                contenu normatif PGR existant
howtos             contenu procédural séparé
snippets            contenu court/contextualisé séparé

Les dépôts de contenu ne sont pas fusionnés dans PGR et ne sont pas requis comme submodules Git du dépôt applicatif. Leur localisation et leurs credentials sont de la configuration de déploiement.