159 lines
15 KiB
Markdown
159 lines
15 KiB
Markdown
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
||
<!-- version: 9 -->
|
||
|
||
# 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` | `alpha.4` | frontend durable TypeScript |
|
||
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | `alpha.4` | package manager/lockfile/scripts explicites |
|
||
| `550-VITE` | `ADOPT` puisque Vite est retenu | `alpha.4` | dev server/build/cache/outputs |
|
||
| `560-CSS_SASS` | `ADOPT` | `alpha.4` | CSS/Sass et outputs |
|
||
| `700-FRAMEWORKS` | `ADOPT` | `alpha.5` | 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` | `alpha.4` | frontend indépendant du host |
|
||
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | `alpha.4+` | 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 ; actif depuis `alpha.2` |
|
||
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; les manifests Cargo restent le contrat versionné |
|
||
| Actix Web | `KEEP-LOCAL` | trois launchers matérialisés en `alpha.5` et composition partagée dans `knowledge-web-lib` |
|
||
| Maud | `KEEP-LOCAL` | rendu SSR commun matérialisé dans `knowledge-web-lib` en `alpha.5` |
|
||
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
|
||
| Package manager frontend | `KEEP-LOCAL` | npm sélectionné en `alpha.4` ; `package-lock.json` versionné |
|
||
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview des templates et assets de référence ; manifest de production consommé par l’intégration Maud |
|
||
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source de la chaîne de validation Web et des assets réellement servis par les pages Maud |
|
||
| Bootstrap | `KEEP-LOCAL` | framework CSS retenu pour les templates de référence et le rendu Maud ; jamais règle PGR universelle |
|
||
| Racine(s) frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` pour les références statiques et assets communs |
|
||
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; le markup runtime est adapté et servi par Maud |
|
||
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` en `alpha.5`, avec dev-origin/manifest/base-path configurables |
|
||
| 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 |
|
||
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte encore différée |
|
||
| Quatrième application d'administration | `DEFER` | peut agréger du transverse plus tard mais ne remplace jamais les frontières admin locales |
|
||
| Modèle rôles/capabilities | `DEFER` | séparer identité partagée et autorisations métier avant de figer enums/scopes |
|
||
| 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.
|
||
|
||
La sélection Web `alpha.4` conserve une seule baseline partagée tant qu'aucune divergence réelle entre les trois façades ne justifie plusieurs packages. Les entrées spécifiques pourront être ajoutées dans ce package avant toute duplication de toolchain.
|
||
|
||
## Nomenclature de crates
|
||
|
||
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 sont matérialisés depuis `alpha.5`. Leurs `main.rs` restent minces et délèguent à `knowledge-web-lib`. Chacun conserve le contrat de pouvoir protéger sa propre surface d'administration métier lorsque cette surface sera implémentée.
|
||
|
||
Les responsabilités matérialisées sont :
|
||
|
||
```text
|
||
knowledge-domain-lib types métier stables de famille/source ; aucune dépendance Actix/Git-provider/forge/PostgreSQL
|
||
knowledge-git-api contrat passif GitRepository ; implémentations génériques remplaçables derrière cette frontière
|
||
knowledge-sync-api contrat passif RepositoryEventSource et signaux de réconciliation ; plusieurs mécanismes producteurs prévus
|
||
knowledge-web-lib composition Actix/Maud partagée, résolution Vite dev/manifest et service des assets
|
||
knowledge-pgr-server launcher PGR mince
|
||
knowledge-howtos-server launcher HOWTOs mince
|
||
knowledge-snippets-server launcher snippets mince
|
||
```
|
||
|
||
Les responsabilités suivantes restent candidates et ne deviennent des packages que lorsqu'elles possèdent un ownership réel :
|
||
|
||
```text
|
||
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 de knowledge-git-api
|
||
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
|
||
knowledge-forge-gitea-lib adapter Gitea optionnel
|
||
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.
|
||
|
||
## Corpus auth/admin étudié en alpha.2
|
||
|
||
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` sont 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 de plateforme ;
|
||
- l'autorisation privilégiée propre aux cas d'usage de chaque application ;
|
||
- une éventuelle façade d'administration transversale ultérieure.
|
||
|
||
Elles ne justifient pas encore de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA comme scope `0.0.1`.
|
||
|
||
## Décisions à rouvrir
|
||
|
||
La réconciliation `beta.1` confirme que les `DEFER` suivants restent légitimes : adapter Gitea, driver/migrations PostgreSQL, moteur de recherche, fournisseur d'identité externe, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet et noms de crates non encore possédés par une responsabilité réelle.
|
||
|
||
La prochaine release engagée `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture. Elle ne lève aucun des `DEFER` ci-dessus par elle-même.
|
||
|
||
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é.
|