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