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

0.0.1-alpha.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 21:04:10 +02:00
commit 116219f860
15 changed files with 1505 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/architecture/001-PROJECT_PROFILE.md Normal file
View File

@@ -0,0 +1,112 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 1 -->
# Profil du projet Knowledge
## Baseline autoritaire
Le cadrage initial repose sur :
```text
PGR stable tag v0.1.1
PGR archive SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
PGR publish report pgr-0.1.1-publish.001-report.md = PASS
Knowledge prompt prompts/001-V0_0_1_START_PROMPT.md
```
L'archive PGR observée possède `VERSION = 0.1.1`, `292` entrées ZIP, `256` fichiers, `36` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Les `48` tests Python et les audits Markdown headers/tables/links de la stable ont été rejoués avant préparation de cette tranche et sont propres.
Cette constatation de prévalidation ne remplace aucune gate opérateur Knowledge.
## Nature de l'instanciation
Knowledge est un nouveau projet. La procédure normative d'adoption d'un dépôt existant `230-ADOPTION.md` n'est donc pas activée comme owner de migration.
Le prompt de démarrage exige néanmoins une matrice `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`. Les mêmes libellés sont utilisés ci-dessous pour rendre explicite la relation entre PGR et les décisions fondatrices Knowledge :
- `ADOPT` — contrat PGR applicable retenu ;
- `KEEP-LOCAL` — choix propre à Knowledge, non possédé par un owner PGR plus spécifique et compatible avec les contrats adoptés ;
- `OVERRIDE` — règle PGR applicable remplacée localement ;
- `DEFER` — choix volontairement reporté avec condition de reprise.
## Owners et skeletons applicables
| Élément | Décision | Matérialisation | Motif |
|----------------------------------------------|---------------------------------|-----------------|----------------------------------------------|
| `200-GOVERNANCE` | `ADOPT` | `alpha.1` | lifecycle/version locale |
| `210-WORKFLOW` | `ADOPT` | `alpha.1` | plan/delta/history/handoff |
| `220-SKELETONS` | `ADOPT` pour l'instanciation | `alpha.1` | composition explicite sans copie mécanique |
| `300-DOCUMENTATION` | `ADOPT` | `alpha.1` | rôles documentaires et taxonomie utile |
| `400-VALIDATION` | `ADOPT` | `alpha.1` | preuves proportionnées et autorité opérateur |
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | `alpha.2` | backend Rust/workspace Cargo contrôlé |
| `530-TYPESCRIPT` | `ADOPT` | tranche Web | frontend durable TypeScript |
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | tranche Web | package manager/lockfile/scripts explicites |
| `550-VITE` | `ADOPT` puisque Vite est retenu | tranche Web | dev server/build/cache/outputs |
| `560-CSS_SASS` | `ADOPT` | tranche Web | CSS/Sass et outputs |
| `700-FRAMEWORKS` | `ADOPT` | avec Actix/Maud | cadre générique des frameworks |
| `710-TAURI` | `DEFER` / non applicable | hors `0.0.1` | aucun host desktop/mobile Tauri |
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` | `alpha.1` | fondation locale PGR |
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` | `alpha.2` | workspace Rust contrôlé |
| skeleton `003-WEB_FRONTEND` | `ADOPT` | tranche Web | frontend indépendant du host |
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | tranche Web | restore/typecheck/build/smoke proportionnés |
Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont pas sélectionnés.
## 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 |
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 :
```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-git-lib implémentation Git générique
knowledge-store-postgres-lib état applicatif PostgreSQL
knowledge-forge-gitea-lib adapter Gitea optionnel
knowledge-server composition HTTP/SSR et point d'entrée exécutable
```
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.
## 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`.

237
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md Normal file
View 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.