Shared Core Submodule in Dotkernel Headless Platform

Dotkernel has implemented a Headless solution made up of these applications:

• Dotkernel API – a REST API, the root of the platform.
• Dotkernel Admin – (optional) complementary backend management.
• Dotkernel Queue – (optional) queue management microservice.

This is effectively a Headless CMS architecture where the Dotkernel Admin manages the data via the database. The same data is independently exposed by Dotkernel API and used by Dotkernel Queue.

What is the Core submodule?

The Core submodule is a common codebase set up to be used by the applications you added to your project. It can just as well work for any project setup, e.g. two APIs, one Admin, 3 Frontends.

By having a common module in your Dotkernel applications, you ensure that each of them uses entities and services in the same way. Thus, rather than making e.g. an update in each application’s services, you only update the relevant service in the Core once and sync it in each application.

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.

How do I create a Core submodule?

The full steps for creating a submodule are described in 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 a 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>:

git submodule add <url>

You can have multiple submodules, but for this article we will only create the Core submodule.

The .gitmodules file maps the submodule’s 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 has 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):

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:

git submodule init
git submodule update

Do not forget to delete the existing Core module before adding the submodule to other applications.

How do I use the Core submodule?

Once the shared Core submodule is separated and imported into each application, your platform will look something like this:

• API + Core
• Admin + Core
• Queue + Core

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. So in total you 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:

• 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 one application.

Why the Core submodule is effective

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 ourside connections as requirements arise.

Additional Resources

• Dotkernel Git Repositories

---