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

Architecture de fondation Knowledge

Décision structurante

Knowledge est un workspace modulaire multi-app. Il possède trois applications Actix Web déployables séparément pour PGR, HOWTOs et snippets, et des bibliothèques communes pour les responsabilités réellement partagées.

Cette décision ne crée pas une architecture de microservices distribués : les trois launchers restent des couches de composition minces, peuvent utiliser le même PostgreSQL et partagent les mêmes contrats de domaine, Git, stockage et synchronisation lorsque leur ownership est commun.

Le principe directeur reste :

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

Workspace Rust matérialisé

alpha.2 instancie le skeleton PGR 002-RUST_CARGO_WORKSPACE avec une première crate knowledge-domain-lib. Cette crate possède la frontière de domaine commune mais n'introduit pas encore les contrats Git/synchronisation réservés à alpha.3.

Le workspace est une application déployable à train de release unique ; Cargo.lock est donc versionné pour conserver la résolution effectivement vérifiée. Les artefacts Cargo sont dirigés hors du dépôt vers ../builds/sasedev-knowledge/target/.

Vue de responsabilités

pgr.sasedev.com          howtos.sasedev.com       snippets.sasedev.com
        |                         |                         |
knowledge-pgr-server     knowledge-howtos-server  knowledge-snippets-server
        \________________________|________________________/
                                 |
                                 v
                       application use cases
                                 |
          +----------------------+-----------------------+
          |                      |                       |
          v                      v                       v
 content/domain contracts   GitRepository        RepositoryEventSource
          |                      |                       |
          |                      v                       v
          |              Git local/remotes      explicit/poll/hook/webhook
          |
          +---------------------> GitForge (optionnel)
          |                       Gitea/autre forge
          |
          +---------------------> PostgreSQL partagé
          |                       état/index/relations/jobs
          |
          +---------------------> projections/cache locales
                                  lecture/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. Applications publiques

Les trois façades publiques sont des unités de déploiement distinctes :

knowledge-pgr-server       -> famille PGR
knowledge-howtos-server    -> famille HOWTO
knowledge-snippets-server  -> famille snippet

Chaque serveur :

• compose les mêmes bibliothèques communes lorsque la responsabilité est réellement partagée ;
• possède sa configuration de source(s) Git et de publication ;
• peut être déployé et dimensionné indépendamment ;
• ne porte pas de logique métier dupliquée dans main.rs ;
• peut utiliser le même PostgreSQL logique que les deux autres applications.

La topologie d'administration reste DEFER. Une future application d'administration séparée n'est créée que si son boundary de déploiement devient réellement utile.

2. Application et domaine

Le domaine porte les concepts durables : famille de contenu, 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 une source, 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.

Le domaine ne suppose pas qu'une famille possède exactement un repository. Il manipule des identités de source configurables afin de permettre plusieurs repositories PGR/HOWTO/snippet à l'avenir sans refonte du modèle.

3. 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.

La baseline prévoit au moins trois sources Git indépendantes :

pgr       source primaire de knowledge-pgr-server
howtos    source primaire de knowledge-howtos-server
snippets  source primaire de knowledge-snippets-server

Ce mapping est configurable et extensible ; il ne devient pas un match codé en dur sur trois repositories.

4. 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.

5. É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(source_id)
  -> 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 selon la famille
  -> 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.

La synchronisation peut être déclenchée par chacun des trois serveurs au début. Un worker séparé n'est créé que si un besoin d'ownership/lifecycle distinct apparaît.

6. Propositions et revues

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

auteur
famille et source 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.

7. 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
source Git
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.

8. PostgreSQL partagé, index, recherche et cache

La baseline retient une base PostgreSQL logique partagée par les trois applications.

Ce choix est justifié par l'état transversal : identités, sessions, propositions, synchronisation, relations entre familles, index et recherche. Il évite trois bases divergentes pour des concepts qui appartiennent à la même plateforme.

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.

Les enregistrements dérivés doivent porter au minimum l'identité de famille/source et la révision Git afin de savoir exactement quel contenu ils représentent.

Une séparation physique de bases ou de schémas par application reste possible ultérieurement si une contrainte de sécurité, disponibilité, charge ou ownership la justifie. Elle n'est pas la baseline de fondation.

9. Rendu et publication

Chaque application publique sélectionne et publie uniquement les familles/sources qui lui sont autorisées.

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é.

La stratégie exacte de partage des assets/frontend entre les trois applications reste DEFER jusqu'à la tranche Web : un package commun n'est créé que si du code/assets sont réellement communs.

10. 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é.

Chaque application doit pouvoir protéger sa propre surface d'administration métier :

knowledge-pgr-server       -> administration PGR
knowledge-howtos-server    -> administration HOWTOs
knowledge-snippets-server  -> administration snippets

Les chemins HTTP exacts restent DEFER. Les exemples /admin, /adminapi, /login ou autres observés dans les corpus historiques ne sont pas adoptés comme convention Knowledge.

Une quatrième application d'administration MAY être créée ultérieurement si une vraie responsabilité transversale apparaît. Elle pourra agréger comptes, sources, jobs, propositions ou autres vues communes, mais MUST NOT remplacer les contrôles d'autorisation propres aux trois applications.

Une UI complète reste hors scope 0.0.1.

11. Authentification et autorisation

Le domaine doit distinguer identité, authentification, rôle/capacité et action autorisée. L'identité et les sessions peuvent être transversales via PostgreSQL partagé ; l'autorisation métier reste vérifiée côté serveur dans chaque application.

Le fournisseur d'identité, les URLs de login, le modèle détaillé de rôles/capabilities, OAuth2/OIDC et MFA restent différés.

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

Le partage d'une base PostgreSQL facilite une identité et des autorisations transversales aux trois façades sans imposer trois silos de comptes.

12. 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.

13. 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 source.

État applicatif PostgreSQL partagé

• utilisateurs/sessions ;
• propositions et revue ;
• commentaires/audit applicatif ;
• configuration logique des sources ;
• mapping source/famille/application ;
• dernière révision synchronisée/indexée par source ;
• index et recherche dérivés ;
• relations calculées entre familles ;
• 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, workspace et gouvernance de la plateforme
pgr                source Git normative PGR existante
howtos             source Git procédurale séparée
snippets            source Git courte/contextualisée séparée

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.