first commit

docs/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Architecture de netslim-core
+
+`netslim-core` fournit un noyau technique et des modules réutilisables pour plusieurs applications.
+
+## Contenu du package
+
+- `src/Kernel/` : bootstrap, runtime, container DI, routing, migrations, Twig, checks de démarrage.
+- `src/Identity/` : identité, authentification, comptes, autorisation et reset de mot de passe.
+- `src/Settings/` : paramètres applicatifs clé / valeur typés.
+- `src/AuditLog/` : journalisation des actions transverses.
+- `src/Notifications/` : envoi et suivi des emails transactionnels.
+- `src/Taxonomy/` : taxonomie réutilisable et contrats publics associés.
+- `src/Media/` : médiathèque partagée et contrats publics associés.
+
+## Principes
+
+- un seul runtime applicatif par projet consommateur ;
+- les projets consommateurs possèdent leurs templates, assets, points d’entrée HTTP et leurs modules métier propres ;
+- tous les chemins runtime persistants (logs, cache, base SQLite, médias) sont résolus depuis le projet consommateur ;
+- les dépendances inter-modules passent par des contrats publics minimaux ;
+- le noyau ne connaît pas le métier applicatif des projets consommateurs ;
+- les exigences d'environnement métier (par exemple le provisionnement admin d'`Identity`) restent portées par les modules concernés, pas par le bootstrap du noyau.
+
+## Surface publique et frontière package / application
+
+Le package expose comme points d'intégration :
+- `Netig\Netslim\Kernel\Runtime\...` pour le bootstrap et le runtime ;
+- les interfaces applicatives publiques des modules partagés ;
+- les contrats publics sous `*/Contracts/` ;
+- les classes `*Module`.
+
+Les implémentations `Infrastructure/`, les repositories PDO, les détails de wiring et les templates internes doivent être considérés comme des détails d'implémentation. Voir aussi `docs/PUBLIC_API.md`.
+
+## Responsabilités d'une application consommatrice
+
+Une application qui consomme `netslim-core` doit fournir :
+- un manifeste de modules (`config/modules.php`) ;
+- un point d'entrée HTTP ;
+- les templates réellement applicatifs ;
+- les assets attendus par les layouts et écrans qu'elle utilise.
+
+Contrats implicites actuels côté UI :
+- `@Kernel/layout.twig` attend `/assets/css/main.css` ;
+- l'écran admin de `Media` attend `/assets/js/media-admin.js` côté projet consommateur ;
+- `Identity` ne suppose pas la présence d'un module éditorial : la destination back-office se règle via `ADMIN_HOME_PATH` (défaut : `/admin`).
+
+Contraintes d'environnement côté modules :
+- `Identity` requiert `ADMIN_*` uniquement si le projet exécute le provisionnement initial du compte administrateur ;
+- `Notifications` requiert les variables `MAIL_*` seulement si l'application active l'envoi réel d'emails transactionnels.
+
+> Quand `netslim-core` est installé via Composer, les chemins runtime détectent automatiquement la racine du projet consommateur pour les scripts CLI et les suites de tests qui n'appellent pas explicitement `Bootstrap::create()`.

docs/DEVELOPMENT.md

@@ -0,0 +1,95 @@
+# Développement
+
+Ce document sert de guide quotidien pour travailler sur `netslim-core`.
+
+## Démarrage local
+
+Prérequis : PHP 8.4+, Composer, extensions `pdo`, `pdo_sqlite`, `fileinfo`, `gd`, `json`, `mbstring`, `session`, `dom`, `simplexml`.
+
+```bash
+composer install
+composer qa
+```
+
+## Ce que contient le dépôt
+
+- `Kernel/` : runtime, HTTP, persistence, mail, html, pagination, support
+- `Identity/` : authentification, utilisateurs et autorisation transverse
+- `Settings/` : paramètres applicatifs typés
+- `AuditLog/` : journal d'audit partagé
+- `Notifications/` : notifications et emails transactionnels
+- `Taxonomy/` : taxons réutilisables
+- `Media/` : médiathèque transverse
+
+Le dépôt ne contient pas d'application concrète : c'est le socle partagé.
+Une application consommatrice fournit son propre `config/modules.php`, son point d'entrée HTTP, ses templates applicatifs et ses assets.
+Les répertoires runtime (`var/`, `database/`, `public/media/`) appartiennent toujours au projet consommateur, même quand le core est installé sous `vendor/`.
+
+## Où placer une modification ?
+
+### Backend
+
+- `Domain/` : entités, règles métier, contrats métier
+- `Application/` : cas d'usage, services applicatifs, commandes, ports
+- `Infrastructure/` : implémentations concrètes, PDO, stockage, mail, bindings DI
+- `UI/` : contrôleurs, request objects, templates, extensions Twig
+
+### Code transverse
+
+`Kernel/` reste limité au transverse et se découpe en sous-modules explicites : `Runtime/`, `Http/`, `Persistence/`, `Mail/`, `Html/`, `Pagination/` et `Support/`.
+En cas d'hésitation, commencer dans le domaine concerné puis extraire vers `Kernel` à la deuxième vraie réutilisation.
+
+### Checklist avant d'ajouter quelque chose dans `Kernel/Support`
+
+Valider les trois points suivants :
+
+- ce code sert déjà à au moins deux domaines ou représente une primitive transverse évidente ;
+- il ne dépend ni d'un domaine métier, ni de Slim, Twig, PSR-7 ou d'une implémentation d'infrastructure ;
+- la PR met à jour à la fois la documentation et l'allow list des tests d'architecture.
+
+## Faire évoluer un domaine existant
+
+Ordre recommandé :
+
+1. adapter le contrat ou l'interface de service si nécessaire ;
+2. décider si la modification reste une lecture simple ou mérite un `UseCase` + éventuelle `Command` ;
+3. faire évoluer le repository ou le port technique ;
+4. adapter le contrôleur et les vues sans court-circuiter le service applicatif ;
+5. mettre à jour les tests et la documentation utile.
+
+## Ajouter un nouveau domaine
+
+Créer systématiquement :
+
+1. l'entité et les contrats du domaine ;
+2. l'interface de service ;
+3. le repository interface ;
+4. l'implémentation `Infrastructure/` ;
+5. le contrôleur et les templates ;
+6. `Infrastructure/dependencies.php` ;
+7. `UI/Http/Routes.php` ;
+8. `<Domaine>Module.php` ;
+9. les tests dans `tests/<Domaine>/`.
+
+Pour les frontières et dépendances autorisées, se reporter à [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Vérifications avant push
+
+```bash
+composer test
+composer stan
+composer cs:check
+```
+
+Raccourci utile :
+
+```bash
+composer qa
+```
+
+
+## Variables d'environnement et provisionnement
+
+Le bootstrap du noyau requiert seulement l'environnement technique commun (comme `APP_URL`). Les variables `ADMIN_*` sont nécessaires quand une application active `Identity` et exécute le provisionnement initial du compte administrateur. Les variables `MAIL_*` deviennent nécessaires uniquement si l'application active `Notifications` et envoie réellement des emails transactionnels.
+
+> Quand `netslim-core` est installé via Composer, les chemins runtime détectent automatiquement la racine du projet consommateur pour les scripts CLI et les suites de tests qui n'appellent pas explicitement `Bootstrap::create()`.

docs/MODULES.md

@@ -0,0 +1,35 @@
+# Modules fournis par netslim-core
+
+## Kernel
+Socle technique : bootstrap, DI, routing, Twig, migrations, checks de démarrage.
+
+Les layouts `@Kernel` fournissent la structure HTML partagée, mais l'application consommatrice reste responsable de servir ses assets front (`/assets/css/main.css`).
+
+## Identity
+Gestion des comptes, authentification, administration des utilisateurs et autorisation fine basée sur des permissions.
+
+## Settings
+Paramètres applicatifs clé / valeur typés, utilisables par plusieurs projets sans recréer un mini back-office de configuration dans chaque application.
+
+## AuditLog
+Journal d'audit transversal pour tracer les actions sensibles ou structurantes sur des ressources métier.
+
+## Notifications
+Envoi et suivi des emails transactionnels. Le module s'appuie sur le service mail du noyau et conserve un historique des envois réussis ou échoués.
+
+Une application consommatrice qui active ce module doit fournir les variables d'environnement `MAIL_*` nécessaires au transport SMTP.
+
+## Taxonomy
+Gestion de termes de taxonomie réutilisables. Les modules consommateurs gardent la propriété des relations d’usage.
+
+## Media
+Gestion de la médiathèque. Les modules consommateurs utilisent les contrats publics pour exposer les usages des médias.
+
+L'UI admin de `Media` suppose qu'un projet consommateur serve un script applicatif sous `/assets/js/media-admin.js`.
+
+Le module `Identity` peut être intégré sans module éditorial : la redirection vers le back-office après connexion ou refus d'autorisation est pilotée par `ADMIN_HOME_PATH` (défaut : `/admin`).
+
+
+## Frontière publique
+
+Les points d'intégration supportés pour une application consommatrice sont détaillés dans `docs/PUBLIC_API.md`.

docs/PUBLIC_API.md

@@ -0,0 +1,44 @@
+# API publique et API interne de netslim-core
+
+Ce document définit la frontière de support du package `netslim-core`.
+
+## API publique
+
+Les applications consommatrices peuvent dépendre des éléments suivants :
+
+- le namespace `Netig\Netslim\Kernel\Runtime\...` nécessaire au bootstrap, au runtime et à la découverte des modules ;
+- les classes `*Module` exposées par les modules partagés (`IdentityModule`, `SettingsModule`, `AuditLogModule`, `NotificationsModule`, `TaxonomyModule`, `MediaModule`, `KernelModule`) ;
+- les interfaces applicatives explicitement exposées par les modules (`Identity\Application\*ServiceInterface`, `Settings\Application\SettingsServiceInterface`, `AuditLog\Application\AuditLogServiceInterface`, `Notifications\Application\NotificationServiceInterface`, `Taxonomy\Application\TaxonomyServiceInterface`, `Media\Application\MediaServiceInterface`) ;
+- les contrats publics sous `Netig\Netslim\*/Contracts/` ;
+- les conventions documentées de `config/modules.php`, `public/index.php` et des chemins runtime résolus côté projet consommateur ;
+- les layouts et partials Twig documentés sous `@Kernel/...` quand l'application choisit de les réutiliser.
+
+## API interne
+
+Les éléments suivants doivent être considérés comme des détails d'implémentation du package :
+
+- tout `Infrastructure/` (repositories PDO, stockage local, wiring DI, maintenance post-migration) ;
+- tout `Application/UseCase/` et les services applicatifs non documentés comme contrats ;
+- les entités de domaine utilisées en interne par les modules ;
+- les vérifications de démarrage propres aux modules ;
+- les templates Twig non documentés comme points d'intégration.
+
+Une application consommatrice ne devrait pas dépendre directement de ces éléments internes.
+
+## Règle pratique
+
+Quand un projet applicatif a besoin d'une capacité partagée, il doit préférer :
+
+1. un contrat public existant dans `Contracts/` ;
+2. à défaut, une extension documentée du runtime ou d'un module ;
+3. en dernier recours, une évolution du core qui ajoute un nouveau point d'intégration public.
+
+Éviter de se brancher directement sur des classes internes permet de garder le core versionnable et évolutif.
+
+## Stabilité attendue
+
+- l'API publique est la cible de compatibilité entre versions ;
+- l'API interne peut évoluer à tout moment tant que le comportement public documenté reste cohérent ;
+- tout nouveau point d'extension réutilisable doit être documenté ici ou dans `README.md` / `MODULES.md`.
+
+## Versionnement

docs/README.md

@@ -0,0 +1,29 @@
+# Documentation
+
+Ce dossier contient les documents de référence du socle `netslim-core`.
+
+## Par où commencer ?
+
+- **Je découvre le dépôt** → [../README.md](../README.md)
+- **Je veux comprendre les frontières et dépendances** → [ARCHITECTURE.md](ARCHITECTURE.md)
+- **Je veux connaître les conventions de module** → [MODULES.md](MODULES.md)
+- **Je veux savoir ce qui est public ou interne** → [PUBLIC_API.md](PUBLIC_API.md)
+- **Je travaille au quotidien sur le dépôt** → [DEVELOPMENT.md](DEVELOPMENT.md)
+- **Je contribue au dépôt** → [../CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## Si tu ne lis que trois documents
+
+1. [../README.md](../README.md) pour comprendre ce que contient le dépôt
+2. [ARCHITECTURE.md](ARCHITECTURE.md) avant toute évolution structurelle
+3. [PUBLIC_API.md](PUBLIC_API.md) avant d'utiliser le core comme dépendance applicative
+
+## Rôle de chaque document
+
+| Document | Rôle |
+|---|---|
+| [../README.md](../README.md) | Vue d'ensemble et mode d'installation du socle |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Référence sur les modules, les couches et les dépendances autorisées |
+| [MODULES.md](MODULES.md) | Charte de module et conventions de frontière |
+| [PUBLIC_API.md](PUBLIC_API.md) | Délimitation de l'API publique et de l'API interne |
+| [DEVELOPMENT.md](DEVELOPMENT.md) | Guide de travail quotidien, variables d'environnement et checklist avant push |
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) | Règles de contribution et attentes sur les tests |