<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 5 -->

# 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               | `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 :

```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`.