sasedev-knowledge/docs/architecture/001-PROJECT_PROFILE.md

Profil du projet Knowledge

Baseline autoritaire

Le cadrage initial repose sur :

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	DEFER	choisir dans la tranche Web avant création du manifest/lockfile
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	DEFER	décider en alpha.4 selon le partage réel entre les trois applications et leurs templates de référence
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.

Nomenclature de crates candidate

Les trois packages exécutables sont des boundaries produit retenus :

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 :

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 :

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.

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.