209 lines
18 KiB
Markdown
209 lines
18 KiB
Markdown
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
|
<!-- version: 19 -->
|
|
|
|
# Profil du projet Knowledge
|
|
|
|
## Baseline autoritaire
|
|
|
|
La stable produit depuis laquelle `0.0.4` est ouverte est :
|
|
|
|
```text
|
|
Knowledge stable tag v0.0.3
|
|
Knowledge stable commit b3823972449150b72905930b806d4d15471cddce
|
|
Knowledge archive SHA-256 82407dc2a83be878daa65692f975681428d0adc721ff249c3c9020e3a9d1f29d
|
|
Knowledge publish report sasedev-knowledge-0.0.3-publish.001-report.md = PASS
|
|
Knowledge start prompt prompts/004-V0_0_4_START_PROMPT.md
|
|
```
|
|
|
|
L'archive taggée `v0.0.3` a été vérifiée avant le cadrage `0.0.4-alpha.1` : `VERSION` et le workspace Cargo valent `0.0.3`, les douze deltas et douze histories `0.0.3` sont appariés, `rel.1.fix.1 = PASS` clôt la release et le commentaire ZIP contient le commit stable ci-dessus.
|
|
|
|
La fondation `0.0.1` a été construite sous PGR `v0.1.1`. Cette identité reste historique dans les artefacts `0.0.1`.
|
|
|
|
Le démarrage explicite de `0.0.2` a réévalué PGR et a retenu la stable suivante comme source d'adoption :
|
|
|
|
```text
|
|
PGR stable tag v0.1.3
|
|
PGR stable commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
|
|
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
|
|
PGR publish report pgr-0.1.3-publish.001-report.md = PASS
|
|
```
|
|
|
|
Cette référence est une provenance d'adoption figée. Après matérialisation des contrats retenus, la baseline normative de Knowledge est constituée des artefacts locaux du dépôt Knowledge. Une version ou session future ne consulte pas automatiquement le PGR courant ; une nouvelle comparaison PGR exige une réévaluation explicitement engagée.
|
|
|
|
`0.0.2-alpha.4` matérialise les owners locaux nécessaires et ferme cette adoption comme migration ponctuelle. Le mapping durable est [`003-PGR_ADOPTION_MAP.md`](003-PGR_ADOPTION_MAP.md).
|
|
|
|
L'archive PGR `v0.1.3` vérifiée possède `VERSION = 0.1.3`, `332` entrées ZIP, `290` fichiers, `42` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Son rapport post-tag indique `48/48` tests Python et les audits Markdown propres.
|
|
|
|
Cette prévalidation ne remplace aucune gate opérateur Knowledge.
|
|
|
|
## Historique de l'adoption
|
|
|
|
Knowledge n'est plus un nouveau dépôt à instancier : `0.0.2-alpha.1` migre un projet existant de la baseline PGR `v0.1.1` vers `v0.1.3`.
|
|
|
|
L'owner PGR `230-ADOPTION` devient applicable à cette migration ; son contrat est instancié localement par les décisions suivantes :
|
|
|
|
- partir d'une baseline autoritaire observée ;
|
|
- sélectionner uniquement les owners réellement applicables ;
|
|
- classifier `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` ;
|
|
- préserver les décisions locales compatibles ;
|
|
- ne pas réécrire les commits, deltas, histories ou documents historiques pour simuler une conformité rétroactive ;
|
|
- valider proportionnellement la migration.
|
|
|
|
Les classifications locales restent :
|
|
|
|
- `ADOPT` — contrat PGR applicable retenu ;
|
|
- `KEEP-LOCAL` — choix propre à Knowledge, compatible et non possédé par un owner PGR plus spécifique ;
|
|
- `OVERRIDE` — règle PGR applicable remplacée ou raffinée localement avec justification ;
|
|
- `DEFER` — choix volontairement reporté avec condition de reprise.
|
|
|
|
## Owners locaux après adoption
|
|
|
|
Les responsabilités quotidiennes sont désormais possédées par :
|
|
|
|
```text
|
|
docs/rules/200-GOVERNANCE.md
|
|
docs/rules/210-WORKFLOW.md
|
|
docs/rules/300-DOCUMENTATION.md
|
|
docs/rules/400-VALIDATION.md
|
|
docs/rules/510-RUST_CARGO.md
|
|
docs/rules/530-WEB_FRONTEND.md
|
|
```
|
|
|
|
Le détail de la migration depuis les owners PGR `v0.1.3`, y compris les décisions `KEEP-LOCAL`, les éléments non applicables et les skeletons uniquement historiques, est conservé dans [`003-PGR_ADOPTION_MAP.md`](003-PGR_ADOPTION_MAP.md). Aucun de ces owners locaux ne nécessite de consulter PGR pour être interprété.
|
|
|
|
## Matrice des décisions importantes
|
|
|
|
| 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 |
|
|
| Implémentation Git de `0.0.2` | `KEEP-LOCAL` | processus `git` contrôlé derrière `knowledge-git-api` ; décision réévaluable derrière le contrat |
|
|
| Configuration physique Git | `KEEP-LOCAL` | `knowledge-git-lib` matérialisée en `0.0.2-alpha.2` ; source locale/remote + racine d'état ; pas dans le domaine |
|
|
| Copies Git générées | `KEEP-LOCAL` | racine d'état explicite hors dépôt source, mirrors et snapshots adressés par clé sûre/révision |
|
|
| Écriture Git contrôlée `0.0.3` | `KEEP-LOCAL` | contrat distinct de la lecture, worktree isolé, commit explicite et push de branche gardé par état attendu |
|
|
| Rebase/merge automatique | `DEFER` | reprendre avec un workflow de proposition réellement matérialisé ; divergence = conflit en `0.0.3` |
|
|
| Partage du cache Git entre processus | `DEFER` | état root exclusif à une instance backend en `0.0.2` ; reprendre avec verrouillage inter-processus réel |
|
|
| 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/périodique convergent vers le même cas d'usage ; hooks/webhooks restent accélérateurs |
|
|
| Scheduler périodique concret | `DEFER` | créer seulement lorsque son owner runtime/lifecycle est démontré |
|
|
| Dernière révision observée en `0.0.2` | `KEEP-LOCAL` | fournie par l'appelant et retournée par le cas d'usage ; pas de pseudo-persistance locale |
|
|
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée ; `0.0.4` matérialise sa première fondation sans déplacer la vérité éditoriale de Git |
|
|
| Rust stable / édition 2024 | `ADOPT` | owner local `docs/rules/510-RUST_CARGO.md` |
|
|
| Workspace Cargo | `ADOPT` | configuration locale + owner `510-RUST_CARGO.md` |
|
|
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; manifests Cargo versionnés |
|
|
| Actix Web | `KEEP-LOCAL` | trois launchers existants et composition partagée dans `knowledge-web-lib` |
|
|
| Maud | `KEEP-LOCAL` | rendu SSR commun dans `knowledge-web-lib` |
|
|
| TypeScript | `ADOPT` | owner local `docs/rules/530-WEB_FRONTEND.md` |
|
|
| Package manager frontend | `KEEP-LOCAL` | npm ; `package-lock.json` versionné |
|
|
| Vite | `KEEP-LOCAL` + contrat adopté | owner local Web ; build/preview de références et manifest consommé par Maud |
|
|
| Sass | `KEEP-LOCAL` + contrat adopté | owner local Web ; styles source et assets réellement servis |
|
|
| Bootstrap | `KEEP-LOCAL` | framework CSS local Knowledge, jamais règle PGR universelle |
|
|
| Racine frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` |
|
|
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; rendu runtime Maud |
|
|
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` |
|
|
| Toolkit PostgreSQL | `KEEP-LOCAL` | `tokio-postgres` + `deadpool-postgres`, async/Tokio et SQL explicite ; aucun ORM sélectionné |
|
|
| Migrations PostgreSQL | `KEEP-LOCAL` | SQL versionné possédé par `knowledge-store-postgres-lib`, appliqué explicitement via Refinery |
|
|
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif lorsque ce scope sera engagé |
|
|
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
|
|
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte différée |
|
|
| Quatrième application d'administration | `DEFER` | agréger seulement si une responsabilité transverse apparaît |
|
|
| Modèle rôles/capabilities | `DEFER` | reprendre avec les cas d'usage d'autorisation réels |
|
|
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel |
|
|
| Autres noms de crates | `DEFER` | créer uniquement lorsque l'ownership est démontré |
|
|
|
|
## Nomenclature de crates
|
|
|
|
Les packages matérialisés sont :
|
|
|
|
```text
|
|
knowledge-domain-lib types métier stables de famille/source
|
|
knowledge-app-lib cas d'usage applicatifs partagés, dont synchronisation de lecture
|
|
knowledge-git-api contrat passif GitRepository provider-neutral
|
|
knowledge-git-lib implémentation Git générique + mirror/refresh/resolve/snapshot + état local contrôlé
|
|
knowledge-sync-api contrat passif RepositoryEventSource
|
|
knowledge-web-lib composition Actix/Maud/Vite partagée
|
|
knowledge-pgr-server launcher PGR mince
|
|
knowledge-howtos-server launcher HOWTOs mince
|
|
knowledge-snippets-server launcher snippets mince
|
|
```
|
|
|
|
`knowledge-git-lib` devient réelle en `0.0.2-alpha.2` puis implémente le chemin de lecture Git dans `alpha.3`. `knowledge-app-lib` devient réelle en `0.0.2-alpha.5` : l'orchestration refresh / résolution / comparaison / snapshot confirme une responsabilité application partagée distincte du backend Git et des launchers.
|
|
|
|
`0.0.4-alpha.1` retient comme prochaine responsabilité réelle, sans encore la matérialiser dans cette tranche :
|
|
|
|
```text
|
|
knowledge-store-postgres-lib pool, migrations et état applicatif PostgreSQL partagé
|
|
```
|
|
|
|
Les responsabilités suivantes restent candidates et non matérialisées :
|
|
|
|
```text
|
|
knowledge-forge-gitea-lib adapter Gitea optionnel
|
|
knowledge-logging-lib diagnostics partagés, seulement sur besoin multi-runtime réel
|
|
```
|
|
|
|
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, Git process et PostgreSQL ;
|
|
- garder les adapters/implémentations 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.
|
|
|
|
## Corpus auth/admin étudié en 0.0.1
|
|
|
|
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` restent des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
|
|
|
|
Elles justifient de conserver séparées l'identité/authentification partagée, l'autorisation privilégiée propre à chaque application et une éventuelle façade transverse ultérieure. Elles ne justifient toujours pas de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA pendant `0.0.2`.
|
|
|
|
## Résultat de l'adoption PGR 0.1.3
|
|
|
|
`0.0.2-alpha.4` ferme l'adoption comme migration ponctuelle :
|
|
|
|
- les owners nécessaires sont adaptés et possédés localement ;
|
|
- les règles Web externes applicables sont consolidées en un owner Knowledge plutôt que copiées en quatre documents ;
|
|
- les skeletons restent une provenance d'instanciation, pas des dépendances normatives ;
|
|
- les scripts génériques utiles sont sélectionnés localement et les variantes locales restent autoritaires ;
|
|
- les futurs prompts de session repartent de Knowledge seul ;
|
|
- une nouvelle stable PGR n'a aucun effet tant qu'une réévaluation n'est pas explicitement planifiée ;
|
|
- les artefacts historiques `0.0.1` et les tranches antérieures de `0.0.2` restent inchangés.
|
|
|
|
## Réconciliation beta et décisions différées
|
|
|
|
`0.0.2-beta.1` confirme que le scope alpha est matérialisé par neuf packages Cargo : contrats domaine/Git/synchronisation, backend Git générique, orchestration application partagée, composition Web et trois launchers. Aucune responsabilité supplémentaire n'est nécessaire pour fermer la mission de lecture/synchronisation de `0.0.2`.
|
|
|
|
Restent différés après `0.0.2` : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, scheduler concret, support explicite submodules/LFS, politique de nettoyage/rétention des snapshots et partage concurrent de la même racine Git entre plusieurs processus.
|
|
|
|
La revue d'horizon `0.0.2-beta.1` n'avait réservé aucune release suivante. L'ouverture explicite de `0.0.3` a consommé uniquement le `DEFER` d'écriture Git contrôlée : worktree d'écriture isolé, commit candidat et push de branche gardé. Rebase/merge automatique et workflow complet de proposition restent différés.
|
|
|
|
La revue `0.0.3-beta.1` sélectionne désormais la fondation PostgreSQL partagée comme prochaine mission `0.0.4`, sans préchoisir son driver/ORM avant l'étude de démarrage. Elle réordonne ensuite l'horizon produit pour rendre visibles les phases de modèles/projections, templates publics, templates admin, intégration Actix/Maud puis workflow de gestion/publication. Gitea, scheduler, recherche avancée, quatrième application admin et partage multi-processus restent différés tant que leurs déclencheurs ne sont pas matérialisés.
|
|
|
|
## Ouverture `0.0.4` — fondation PostgreSQL partagée
|
|
|
|
Après publication vérifiée de `v0.0.3`, `0.0.4-alpha.1` consomme les `DEFER` portant sur le toolkit PostgreSQL et les migrations.
|
|
|
|
La décision locale est :
|
|
|
|
```text
|
|
owner prévu knowledge-store-postgres-lib
|
|
driver tokio-postgres 0.7
|
|
modèle SQL explicite, sans ORM
|
|
pool deadpool-postgres 0.14
|
|
migrations SQL versionné + Refinery 0.9
|
|
premier état source logique + dernière révision synchronisée
|
|
autorité contenu Git
|
|
```
|
|
|
|
Aucune crate n'est créée pendant `alpha.1`. La tranche établit seulement l'étude et le plan qui autoriseront `alpha.2` après gate opérateur `PASS`.
|
|
|
|
La configuration physique Git reste possédée par `knowledge-git-lib`. Le premier schéma PostgreSQL ne stocke pas de credentials Git et ne transforme pas les URLs/paths physiques en vérité métier. La configuration de connexion PostgreSQL est injectée par la composition, non lue implicitement par la future crate de stockage.
|
|
|
|
Les `DEFER` Gitea/forge, scheduler, recherche avancée, auth/capabilities, formats finaux de contenu, quatrième application admin, partage multi-processus de racine Git, LFS/submodules et rétention avancée restent inchangés. L'horizon `0.0.5` à `0.0.10` reste cohérent et n'est pas replanifié par cette étude.
|