0.0.1-alpha.1
This commit is contained in:
237
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
Normal file
237
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
Normal file
@@ -0,0 +1,237 @@
|
||||
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
sync explicite
|
||||
polling
|
||||
hook Git local/serveur
|
||||
webhook de forge
|
||||
watcher filesystem éventuel
|
||||
```
|
||||
|
||||
Toutes convergent vers le même cas d'usage interne :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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.
|
||||
Reference in New Issue
Block a user