Merge pull request #5 from dotkernel/file-structure

updated admin usage page

Author: arhimede

docs/book/v1/admin/usage.md

@@ -1,19 +1,16 @@
 # Usage
 
-Dotkernel API can be installed independently or together with other applications in the Dotkernel suite, based on your business requirements.
+Dotkernel Admin can be installed independently or together with other applications in the Dotkernel suite, based on your business requirements.
 These components are designed to complement each other (out-of-box they are separate codebases):
 
 - **Dotkernel API** exposes the content to 3rd-party frontends or backends.
 - **Dotkernel Admin** (optional) manages the data (create, edit, delete).
 - **Dotkernel Queue** (optional) queue management microservice.
 
-A safe bet is to start with Dotkernel API and integrate it into your existing platform.
-The API can manage the access permissions to keep your data secure:
-
-- Admin-level users create and edit the data for your existing backend.
-- Regular users read the data for your frontend.
+You can start with Dotkernel Admin and integrate it into your existing platform.
+The Admin has built-in reports and graphs that can be configured and customized based on your needs.
 
 Later on you can add:
 
-- Dotkernel Admin for its simple table-based approach, its reports and graphs.
+- Dotkernel API to handle all data manipulation.
 - Dotkernel Queue for its asynchronous task processing.

docs/book/v1/config-provider/benefits.md

@@ -0,0 +1,10 @@
+# Benefits
+
+- **Centralized setup** – Instead of hardcoding bootstrap code, you declare it in a config provider so it's easy to read, change, or extend.
+- **Modular** – Each package can ship with its own config without interfering with others.
+- **Container-friendly** – It works well with frameworks using DI containers like Laminas ServiceManager, PHP-DI, or Pimple.
+- **Standardized service definitions** - It has consistent rules for object creation that are separate from business logic.
+- **Environment-agnostic** - It returns an array that defines dev, test, or prod environments.
+- **Testability** - The consistent, central configuration promotes isolated (e.g. per-module) testing, easier swapping of dependencies and the assertion of pipeline setup (e.g. check if a config key is present).
+
+> **Dotkernel ConfigProviders** have to be **added manually** in `config/config.php`, because all the initial ConfigProviders required to install the applications are already injected.

docs/book/v1/config-provider/functionality.md

@@ -0,0 +1,23 @@
+# How the ConfigProvider works
+
+The ConfigProvider is automatically picked up by the framework during application bootstrap.
+Let's look at it step by step:
+
+- **Merge the global configuration** - All ConfigProviders are merged into one array.
+- **Read the configuration array** - The call is similar to the below and expects an array of entries:
+
+```php
+$config = $container->get('config')['key'] ?? [];
+```
+
+- **Resolve item** - `$app->pipe()` is called to resolve one of the below instances:
+    - Resolve the service name from the container
+    - Wrap the middleware, if an array is provided
+    - Call the closure or invokable object.
+- **Handle errors** - This middleware is the last one in the pipeline to make sure it handles any exceptions.
+- **Execute at runtime** - [Laminas Stratigility](https://docs.laminas.dev/laminas-stratigility/) iterates over the pipeline in the order it was registered.
+    - Each middleware can **handle** the request and return a response, or **delegate** execution to the next middleware in the pipeline, until a `ResponseInterface` is returned to the client.
+
+Below you can see how Mezzio and Dotkernel merge and use ConfigProviders to build the middleware pipeline and dependencies.
+
+![Headless Platform with Core Submodule](https://docs.dotkernel.org/img/headless-platform/ConfigProvider.png)

docs/book/v1/config-provider/introduction.md

@@ -0,0 +1,53 @@
+# Introduction
+
+In PHP, the `ConfigProvider` is a class that is part of an application's bootstrap process.
+It returns an array of configuration, settings, or anything else your application needs.
+In Dotkernel, each application module and package contains a `ConfigProvider` that normally returns:
+
+- Dependency injection mappings.
+- Request Handlers.
+- Template file paths.
+
+Here is an example in Dotkernel, which is an approach similar to Laminas/Mezzio:
+
+```php
+class ConfigProvider
+{
+    public function __invoke(): array
+    {
+        return [
+            'dependencies' => $this->getDependencies(),
+            'templates'    => $this->getTemplates(),
+        ];
+    }
+
+    public function getDependencies(): array
+    {
+        return [
+            'factories'  => [
+                Handler\HomepageHandler::class => Handler\HomepageHandlerFactory::class,
+                Handler\SearchHandler::class   => Handler\SearchHandlerFactory::class,
+            ],
+            'invokables' => [
+                Console\GenerateSearchData::class => Console\GenerateSearchData::class,
+           ],
+        ];
+    }
+
+    public function getTemplates(): array
+    {
+        return [
+            'app'   => [__DIR__ . '/../templates/app'],
+            'error' => [__DIR__ . '/../templates/error'],
+        ];
+    }
+}
+```
+
+All Dotkernel applications and packages use ConfigProviders:
+
+- [Dotkernel API](https://docs.dotkernel.org/api-documentation/)
+- [Dotkernel Admin](https://docs.dotkernel.org/admin-documentation/)
+- [Dotkernel Frontend](https://docs.dotkernel.org/frontend-documentation/)
+- [Dotkernel Light](https://docs.dotkernel.org/light-documentation/)
+- [Dotkernel Packages](https://docs.dotkernel.org/packages/)

mkdocs.yml

@@ -20,8 +20,12 @@ nav:
           - "Creation": v1/core/creation.md
           - "Usage": v1/core/usage.md
           - "Benefits": v1/core/benefits.md
-site_name: headless
-site_description: "Headless Platform"
+      - "ConfigProvider":
+          - "Introduction": v1/config-provider/introduction.md
+          - "Functionality": v1/config-provider/functionality.md
+          - "Benefits": v1/config-provider/benefits.md
+site_name: "Dotkernel Headless Platform"
+site_description: "Dotkernel Headless Platform"
 repo_url: "https://github.com/dotkernel/headless-documentation"
 plugins:
   - search