Sasedev/sasedev-knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.1-alpha.1.fix.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 21:42:49 +02:00
parent 116219f860
commit d632afe11e
14 changed files with 768 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/architecture/001-PROJECT_PROFILE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Profil du projet Knowledge
@@ -54,50 +54,62 @@ Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont p
## Matrice des décisions importantes
| Décision | Classification | Contrat retenu / condition de reprise |
|--------------------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; explicite le produit et évite un nom générique `knowledge` au niveau forge |
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
| PostgreSQL | `KEEP-LOCAL` | état applicatif et projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; matérialisation `alpha.2` |
| `Cargo.lock` | `DEFER` | décider lors de la matérialisation selon le rôle application/workspace et `510` |
| Actix Web | `KEEP-LOCAL` | framework HTTP initial ; PGR ne possède pas de profil Actix dédié |
| Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile |
| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web |
| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue |
| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle |
| Racine frontend | `DEFER` | décider dans la tranche Web ; `frontend/` reste candidat mais non figé par PGR |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Topologie de déploiement | `DEFER` | monolithe modulaire par défaut ; séparer seulement sur contrainte observée |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et le préfixe sont cadrés ; créer une crate uniquement avec ownership réel |
| Décision | Classification | Contrat retenu / condition de reprise |
|--------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée pour l'état transversal et les projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; matérialisation `alpha.2` |
| `Cargo.lock` | `DEFER` | décider lors de la matérialisation selon le rôle application/workspace et `510` |
| Actix Web | `KEEP-LOCAL` | trois launchers serveur distincts ; PGR ne possède pas de profil Actix dédié |
| Maud | `KEEP-LOCAL` | rendu SSR initial lorsque pertinent |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `DEFER` | choisir dans la tranche Web avant création du manifest/lockfile |
| Vite | `KEEP-LOCAL` + owner `550` adopté | choix local cohérent avec la recommandation PGR ; configuration à décider dans la tranche Web |
| Sass | `KEEP-LOCAL` + owner `560` adopté | choix local ; compilation intégrée à la chaîne Web si elle apporte la valeur attendue |
| Bootstrap | `KEEP-LOCAL` | framework CSS local, jamais règle PGR/Tauri/Web universelle |
| Racine(s) frontend | `DEFER` | décider dans la tranche Web selon le partage réel entre les trois applications |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Topologie d'administration | `DEFER` | pas de quatrième application tant qu'un launcher d'administration séparé n'est pas justifié |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et les trois launchers sont cadrés ; créer une crate uniquement avec ownership réel |
Aucun `OVERRIDE` n'est requis à ce stade.
## Nomenclature de crates candidate
Le projet n'instancie pas toutes les crates suivantes en `alpha.1`. Elles décrivent des boundaries candidats et ne deviennent des packages que lorsque leur responsabilité est matérialisée :
Les trois packages exécutables sont des boundaries produit retenus :
```text
knowledge-pgr-server launcher Actix Web de la façade PGR
knowledge-howtos-server launcher Actix Web de la façade HOWTOs
knowledge-snippets-server launcher Actix Web de la façade snippets
```
Ils ne sont pas encore matérialisés en `alpha.1.fix.1`. Lorsqu'ils le seront, leurs `main.rs` resteront minces et composeront les bibliothèques réutilisables.
Les responsabilités de bibliothèques suivantes restent candidates et ne deviennent des packages que lorsqu'elles possèdent un ownership réel :
```text
knowledge-domain-lib contrats et types métier stables
knowledge-app-lib orchestration des use cases, si une séparation dédiée devient utile
knowledge-app-lib orchestration des use cases transversaux, si la séparation apporte une valeur réelle
knowledge-git-lib implémentation Git générique
knowledge-store-postgres-lib état applicatif PostgreSQL
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
knowledge-forge-gitea-lib adapter Gitea optionnel
knowledge-server composition HTTP/SSR et point d'entrée exécutable
knowledge-web-lib composition Web réellement partagée, seulement si les trois serveurs dupliqueraient sinon du code
knowledge-logging-lib diagnostics partagés, seulement lorsque plusieurs runtimes en ont effectivement besoin
```
Règles de création :
@@ -105,8 +117,10 @@ Règles de création :
- ne pas créer une crate uniquement pour refléter un diagramme ;
- ne pas utiliser `-api` sans frontière de contrat indépendante réellement nécessaire ;
- garder le domaine indépendant d'Actix, Gitea et PostgreSQL ;
- garder les adapters dépendants des contrats, jamais l'inverse.
- garder les adapters dépendants des contrats, jamais l'inverse ;
- ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
- ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.
## Décisions à rouvrir
Les `DEFER` sont réexaminés dans la tranche qui consomme réellement la décision. Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé dans `alpha.1`.
Les `DEFER` sont réexaminés dans la tranche qui consomme réellement la décision. Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé dans `alpha.1.fix.1`.

154
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
View File

@@ -1,52 +1,80 @@
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# 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.
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.
Le principe directeur est :
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.
## 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
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. Application et domaine
## 1. Applications publiques
Le domaine porte les concepts durables : source de contenu, révision, proposition, validation, publication, type documentaire et références entre contenus.
Les trois façades publiques sont des unités de déploiement distinctes :
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.
```text
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.
## 2. Git générique
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 :
@@ -65,7 +93,17 @@ 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
La baseline prévoit au moins trois sources Git indépendantes :
```text
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 :
@@ -81,7 +119,7 @@ L'absence d'un adapter forge ne doit pas empêcher la synchronisation d'un dép
Gitea est le premier candidat d'intégration mais n'est pas figé comme dépendance du domaine.
## 4. Événements et synchronisation
## 5. Événements et synchronisation
Le contrat conceptuel `RepositoryEventSource` produit un **signal de synchronisation**, pas une vérité de contenu.
@@ -98,25 +136,27 @@ watcher filesystem éventuel
Toutes convergent vers le même cas d'usage interne :
```text
signal
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
-> 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.
## 5. Propositions et revues
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 :
```text
auteur
cible
famille et source cible
révision Git de base
patch ou contenu proposé
statut
@@ -131,7 +171,7 @@ Si la base n'est plus courante, le workflow doit pouvoir signaler un conflit/reb
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
## 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.
@@ -140,6 +180,7 @@ Le format final des HOWTOs/snippets reste `DEFER`. Le parseur devra néanmoins p
```text
identité logique
famille de contenu
source Git
révision source
métadonnées normalisées
corps rendu/parsé
@@ -149,17 +190,21 @@ 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
## 8. PostgreSQL partagé, index, recherche et cache
L'index/cache est une projection reconstructible du contenu Git.
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`.
Une projection doit garder la révision Git source afin de savoir exactement quel contenu elle représente.
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.
## 8. Rendu et publication
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.
La publication sélectionne une révision autorisée, la valide/indexe puis la rend disponible localement.
## 9. Rendu et publication
Chaque application publique sélectionne et publie uniquement les familles/sources qui lui sont autorisées.
Pour PGR :
@@ -173,19 +218,25 @@ Pour HOWTOs/snippets :
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
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é.
Elle pourra gérer propositions, revues, synchronisation, validation et publication. Une UI complète est hors scope `0.0.1`.
## 10. Authentification et autorisation
La décision entre routes d'administration réparties dans les trois applications et launcher d'administration dédié reste ouverte jusqu'à ce que les besoins d'auth, lifecycle et déploiement soient connus.
## 11. 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
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 :
@@ -200,24 +251,25 @@ Les métadonnées peuvent relier ces familles sans promotion automatique de forc
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
## 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 dépôt.
- refs/tags/branches autorisées par la politique de chaque source.
### État applicatif PostgreSQL
### État applicatif PostgreSQL partagé
- utilisateurs/sessions ;
- propositions et revue ;
- commentaires/audit applicatif ;
- configuration logique des sources ;
- dernière révision synchronisée/indexée ;
- mapping source/famille/application ;
- dernière révision synchronisée/indexée par source ;
- index et recherche dérivés ;
- relations calculées ;
- relations calculées entre familles ;
- jobs de synchronisation/publication ;
- cache/projections reconstructibles.
@@ -228,10 +280,10 @@ Une modification du contenu publié ne doit pas exister uniquement dans PostgreS
## 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é
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.