first commit

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