127 lines
12 KiB
Markdown
127 lines
12 KiB
Markdown
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# 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` ; 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
|
|
|
|
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 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 partagé
|
|
knowledge-forge-gitea-lib adapter Gitea optionnel
|
|
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 :
|
|
|
|
- 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 ;
|
|
- 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.fix.1`.
|