Merge pull request #4 from dotkernel/file-structure

added files for api, admin, core

Author: arhimede

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.