added files for api, admin, core

docs/book/v1/admin/introduction.md

@@ -0,0 +1,11 @@
+# Introduction
+
+Dotkernel Admin is an application (skeleton) intended for quickly setting up an administration site for your platform.
+
+Dotkernel Admin:
+
+- Is a fast and reliable way to manage records in your database with a simple table-based approach
+- Allows you to monitor your platform via its built-in reports and graphs.
+- Contains many graphical components to ensure an intuitive user experience.
+- Has a PSR-Compliant Middleware Stack to promote a lean, modular architecture and create a common ground between components from various sources.
+- Implements [PSR-7](https://www.php-fig.org/psr/psr-7/) (HTTP message interfaces) and [PSR-15](https://www.php-fig.org/psr/psr-15/) (HTTP Server Request Handlers) as defined by the [PHP Framework Interop Group](https://www.php-fig.org/).

docs/book/v1/admin/usage.md

@@ -0,0 +1,19 @@
+# Usage
+
+Dotkernel API 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.
+
+Later on you can add:
+
+- Dotkernel Admin for its simple table-based approach, its reports and graphs.
+- Dotkernel Queue for its asynchronous task processing.

docs/book/v1/api/introduction.md

@@ -0,0 +1,10 @@
+# Introduction
+
+Dotkernel API is a REST API based on the Mezzio skeleton.
+The API is the root or the Dotkernel Headless Platform.
+
+Dotkernel API:
+
+- Ensures that you build a cohesive system that contains an API-first backend with the same architecture and standards support as other Dotkernel tools and applications.
+- Has a PSR-Compliant Middleware Stack to promote a lean, modular architecture and create a common ground between components from various sources.
+- Implements [PSR-7](https://www.php-fig.org/psr/psr-7/) (HTTP message interfaces) and [PSR-15](https://www.php-fig.org/psr/psr-15/) (HTTP Server Request Handlers) as defined by the [PHP Framework Interop Group](https://www.php-fig.org/).

docs/book/v1/api/usage.md

@@ -0,0 +1,19 @@
+# Usage
+
+Dotkernel API 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.
+
+Later on you can add:
+
+- Dotkernel Admin for its simple table-based approach, its reports and graphs.
+- Dotkernel Queue for its asynchronous task processing.

docs/book/v1/core/benefits.md

@@ -0,0 +1,12 @@
+# Benefits of the Core Submodule
+
+This design pattern ensures:
+
+- Design flexibility.
+- Scalability based on future requirements.
+- Consistent, enterprise-level growth, while also being suited for smaller applications.
+- The ability to split the work to multiple developers.
+- Easier bugfixes and onboarding.
+
+As your platform expands, each new application connects to the Dotkernel Headless Platform via the central API which services everything the other applications require.
+This ensures consistency throughout your platform, while allowing any number of outside connections as requirements arise.

docs/book/v1/core/creation.md

@@ -0,0 +1,40 @@
+# Creating a Core Submodule
+
+The full steps for creating a submodule are described in [Git Tools – Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+
+> There is already a Core module in some of the Dotkernel applications, but it works like any other module (App, Page, or User).
+> The Core modules are designed to be a starting point for the module’s transformation into a Git submodule.
+
+First create a new Git repository that will contain the Core code.
+To create the submodule in an application, you need to have Git create the `.gitmodules` file in the root of the main repository by running the command below.
+Use the url from the new repository you just created instead of `<url>`:
+
+```shell
+git submodule add <url>
+```
+
+> You can have multiple submodules, but for this tutorial we will only create the Core submodule.
+
+The `.gitmodules` file maps the submodules and its corresponding local directory within the main project (e.g. `src/Core`).
+This allows Git to manage the submodule correctly, from cloning, to updating, to tracking its changes.
+
+> None of the Dotkernel applications have the .gitmodules file out of the box.
+> Only after isolating the Core into a Git submodule and pushing it to a separate Git repository does it become available to be included into any Dotkernel application.
+
+From now on, any changes to the Core submodule must be commited from within the Core folder, like for any other Git repository, using these commands (simplified version, provided as an example):
+
+```shell
+cd <path/to/submodule>
+git add .
+git commit -m "comment"
+git push
+```
+
+Whenever you clone the project, you simply need to `init` and `update` the submodule with these commands:
+
+```shell
+git submodule init
+git submodule update
+```
+
+> Do not forget to delete the existing Core module before adding the submodule to other applications.

docs/book/v1/core/introduction.md

@@ -0,0 +1,13 @@
+# Introduction
+
+The Core submodule is a common codebase set up to be used by the Dotkernel applications you added to your project.
+The project setup may differ - e.g. two APIs, one Admin, 3 Frontends - but the Core submodule can be included in all of them.
+
+By having a common module in your Dotkernel applications, you ensure that each of them uses entities and services in the same way.
+It helps to make service updates easier to sync in all the application in your platform.
+
+General rules:
+
+- The golden rule for the Core codebase is that it is the only place which manages the database entities.
+- As much as possible, all Doctrine entities must reside in Core.
+- The current location of the Core submodule is `src/Core`.

docs/book/v1/core/usage.md

@@ -0,0 +1,25 @@
+# Using the Core Submodule
+
+Once the shared Core submodule is separated and imported into each application, your platform can look like in the example below:
+
+- API + Core
+- Admin + Core
+- Queue + Core
+
+![Headless Platform with Core Submodule](https://docs.dotkernel.org/img/headless-platform/core-queue2.png)
+
+> Each box in the image is a different Git repository.
+
+Whenever work begins on a new feature or update, the devs should normally have the most recent Core in their development environment.
+In our example we have four code bases which will be kept in four separate repositories.
+
+The Dotkernel applications include various entities to get you started quickly.
+This is not a complete list, but it should help you understand what each application is aimed toward, for example:
+
+- The admin has admins, admin logins and settings entities.
+- The api has both users and admins, as well as authentication entities.
+
+There are already shared entities which are identical, so the best place for them is within the Core submodule.
+Whenever you create new shared code, you should add it in the Core submodule and make sure to keep it updated in all your applications.
+
+> This does not mean that all new code should be in Core, as there are plenty of instances when certain functionality is designed to only be used by only one application.

docs/book/v1/introduction.md

@@ -1 +1,13 @@
 # Introduction
+
+The principle of a Headless Platform is to decouple the User Interface (frontend) from the backend services.
+The responses from the platform are then used by another system, such as a website or mobile app.
+
+![Headless Platform](https://docs.dotkernel.org/img/headless-platform/api-comms4.png)
+
+Its design leads to a great deal of versatility in the setup and configuration.
+Here are some of the advantages of the Headless Platform:
+
+- The ability to have multiple frontends, each targeted to various end-users, like desktop vs mobile, iOS vs Android etc.
+- Different frontends (websites) for various niches (younger vs older users) and countries (including localization).
+- Ability to customise separate frontends in terms of design, as well as available features.

docs/book/v1/migration/full-rewrite.md

@@ -0,0 +1,33 @@
+# Full Rewrite or Big Bang Rewrite
+
+A full rewrite is a software migration strategy that implies completely rebuilding the system from scratch in the new architecture or technology.
+
+## How It Works
+
+- You keep the old application in use, as-is.
+- In parallel, you work with the development team to build a new version of the application in the target environment.
+- Once the new application is complete and tested, you redirect all execution to the new application.
+- You decommission the old application.
+
+## Pluses
+
+There are several advantages to this approach:
+
+- Blank slate – No technical debt is carried over to the new application.
+- Optimal architecture – You can code the new application without worrying about legacy code or outdated design patterns.
+- Better maintainability and security – The new code can follow modern best practices which may be incompatible with the old code.
+
+## Minuses
+
+The disadvantages often weigh heavy against choosing this approach:
+
+- High risk – Your release must work on the first try, there’s no partial rollback.
+- Long timeline – There is no immediate user value during development.
+- Expensive – Building a second product in parallel may prove to be just as costly as the original product.
+- Feature drift – Since the old application is still running, any updates performed on it may cause further delay on the development of the new one and greater mismatching of business logic.
+
+## Conclusion
+
+Performing a full rewrite is no easy choice.
+More often than not, the costs are the main reason you would not choose this migration strategy.
+You may find yourself delaying its implementation until you are forced to do so by circumstance.

docs/book/v1/migration/introduction.md

@@ -0,0 +1,17 @@
+# Migrations
+
+When we talk about **migration**, we primarily refer to the **transfer of functionality** (the codebase) from one platform to another, more often from an older architecture like MVC, to a modern one like middleware.
+Still, a complex platform migration may include:
+
+- Replatforming - e.g. from on-premises to the cloud.
+- Refactoring - to improve readability, maintainability, and efficiency.
+- Database or storage migration - to improve execution time and/or security.
+
+The **migration of the software codebase** is the process of moving a software system's source code **to another environment**, which can involve:
+
+- Updating to a newer version of a language or framework.
+- Changing the infrastructure e.g. moving from SQL to NoSQL databases.
+- Replacing designs for security and compliance requirements.
+
+The process ensures that software is kept functional, compatible, and secure as the technology evolves.
+It is also the perfect opportunity to implement modern design patterns recommended by the development community.

docs/book/v1/migration/modular-refactoring.md

@@ -0,0 +1,35 @@
+# Modular Refactoring
+
+The Modular Refactoring is a migration strategy where you break a large, tightly coupled codebase into smaller, independent modules.
+Once the modules are defined, you begin the migration to the new architecture.
+
+## How It Works
+
+- Identify logical boundaries in the business logic.
+Search for sections of code that can function independently.
+- Decouple dependencies.
+Refactor code to reduce direct cross-module calls, often introducing interfaces or APIs for communication.
+- Isolate each module.
+Ensure each module can be built, tested, and deployed separately.
+- Migrate module-by-module.
+Move one module at a time to the new architecture, integrate it back into the system, and test its functionality before moving on.
+
+## Pluses
+
+- Controlled scope – Each migration step is focused on one module.
+- Improved maintainability – As the migration progresses, the system becomes cleaner and more modular.
+- Enables parallel work – You can assign different development teams to migrate different modules at the same time.
+- Lower risk – If a migration fails, only one part of the system is affected.
+
+## Minuses
+
+- Refactoring cost – Breaking a monolith into modules takes time and effort.
+- Possible temporary slowdown – You may need to allocate resources from new feature development to the refactoring effort.
+- Requires strong design discipline – You need to carefully plan modules to avoid repeated rework.
+
+## Conclusion
+
+Modular Refactoring implies a great deal of preparation (proportional to the complexity of the application) before the migration takes place.
+You take e.g. the existing monolith and reorganize it into clearly defined modules, while in the same repository.
+You can the extract the modules into new repositories or move them into microservices, and create interfaces between the old and the new code.
+For the actual code migration, you can opt for the Strangler Fig Pattern.

docs/book/v1/migration/strangler-fig.md

@@ -0,0 +1,27 @@
+# Strangler Fig Pattern or Incremental Migration
+
+The Strangler Fig Pattern is a software migration strategy that implies gradually replacing parts of the old application with new components until the old application is not needed any more.
+
+## How It Works
+
+- Wrap the old application with a routing layer that enables you to selectively redirect incoming requests to either the old code or to new code.
+- Choose an existing feature or service and build it in the new architecture.
+This applies to new features, as well.
+- Replace old features as they are ready to be deployed.
+After development and testing is complete on the new code, reroute traffic for that feature or service to the new code.
+- Decommission the old application.
+Once all features and/or services are migrated, you can shut down the legacy code completely.
+
+## Pluses
+
+- Lower risk – Each change is small, and thus easier to manage and test.
+- Continuous delivery – Users and stakeholders see improvements throughout the development process.
+- Easier rollback – If the new code doesn't work as intended, reroute traffic back to the old code until the new one is revised.
+- Better learning – You discover and fix problems early, adapt your plan more dynamically, and understand the business logic better.
+
+## Conclusion
+
+The Strangler Fig Pattern is the recommended way to go for legacy applications, especially complex ones where a full rewrite would take years and/or millions of dollars.
+You mitigate downtime and risk by handling small, easily manageable sections of code at any given time.
+One restriction for this pattern is that you need to be able to intercept requests and redirect execution.
+The development team can be smaller (since you isolate sections of code you work on) and the development schedule is more adaptable (you can stop at any time because the old application is always there).

mkdocs.yml

@@ -9,6 +9,17 @@ nav:
   - Home: index.md
   - v1:
       - Introduction: v1/introduction.md
+      - API:
+          - "Introduction": v1/api/introduction.md
+          - "Usage": v1/api/usage.md
+      - Admin:
+          - "Introduction": v1/admin/introduction.md
+          - "Usage": v1/admin/usage.md
+      - Core:
+          - "Introduction": v1/core/introduction.md
+          - "Creation": v1/core/creation.md
+          - "Usage": v1/core/usage.md
+          - "Benefits": v1/core/benefits.md
 site_name: headless
 site_description: "Headless Platform"
 repo_url: "https://github.com/dotkernel/headless-documentation"