152 lines
14 KiB
Markdown
152 lines
14 KiB
Markdown
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
|
||
<!-- version: 6 -->
|
||
|
||
# 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 ; actif depuis `alpha.2` |
|
||
| `Cargo.lock` | `KEEP-LOCAL` | versionné : workspace applicatif déployable, résolution reproductible entre opérateur et livraisons |
|
||
| 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 | `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` | mapping d’assets hashés requis en production ; API Rust exacte différée jusqu’à la composition serveur |
|
||
| 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 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.3`. Lorsqu'ils le seront, leurs `main.rs` resteront minces et composeront les bibliothèques réutilisables. Chacun doit pouvoir protéger sa propre surface d'administration métier.
|
||
|
||
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
|
||
```
|
||
|
||
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-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.
|
||
|
||
## 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
|
||
|
||
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`.
|