Microservices Demo Project Anatomy

I've received access to the MicroservicesDemo Starter Project, can you explain the project structure and how I can start building extensions and deploying my own services? I've read https://developer.broadleafcommerce.com/starter-projects/backend-development#project_structure_overview but would still like more detail.

The following will describe in more detail the anatomy of the MicroservicesDemo Starter Project. This specific project is meant to showcase how you can construct a single codebase that produces several different Flex Package compositions. It's important that you understand what a Flex Package entails, as the project structure highly revolves around supporting this concept: Visit https://developer.broadleafcommerce.com/architecture/deployment-flexibility for more details on Flex Package compositions.

Below, we will break down the most important sub-modules Services and Flexpackages in more detail:

Services

The following diagram illustrates the structure of the /services maven sub-module.

1. Each of the Maven sub-modules underneath /services are reflective of a Broadleaf "Microservice" bounded-context. Each of these sub-modules is a normal Spring Boot application that includes a dependency to a specific broadleaf library dependency (see the respective pom.xml for confirmation)

2. With most Broadleaf installations, it is typical for clients to start building extensions, adding their own endpoints, and overriding components that are provided by default with Broadleaf's framework libraries. This is done at each service level. For example, if you needed to extend the Product domain (e.g. as described in this tutorial https://developer.broadleafcommerce.com/tutorials/customize-broadleaf/extending-oob-domain) - you would add that extension to the Catalog service and re-build that particular service jar.

3. Since each service is structured as a simple Spring Boot application, the build configuration allows you to produce both a library dependency JAR which can then be included in a Flex Package composition (e.g. Balanced or Min) OR each service can be used as a standalone executable JAR if you are looking to deploy each service in a Granular fashion. By default, the pom.xml produces the artifact: "demo-*-services.jar", you will want to change this to produce the appropriately named artifact for your organization.

NOTE: If you are looking to deploy each service independently, the service also contains a sample Spring Boot Profile called "localdev" - i.e. /src/main/resources/application-localdev.yml illustrates what configurations and properties are needed in order to run this service independently. For example, the configured listening port for each individual service is going to be different so as not to collide when running things on a single machine

4. Each service also contains a sample dockerfile that shows how to containerize the individual service in the case that you wish to deploy each service in a containerized Granular fashion

NOTE: In some cases, if an organization knows that it will always want to manage and deploy each service in a granular fashion, where each individual service will have its own lifecycle etc... many clients will move each of the individual sub-projects under /services into their own repository. 

Flexpackages

The following diagram illustrates the structure of the /flexpackages maven sub-module.

1. Recall that in the /services sub-module, our build produced the default artifacts "demo-*-services.jar". We will now reference those specific artifacts when building our Flex Package Compositions. For example, in a "Balanced" composition (the default recommended deployment for most Enterprises), we've segmented and categorized all 30+ broadleaf core commerce microservices into 4 main deployments: A Browse deployment, a Cart deployment, a Processing deployment, and a Supporting deployment. If you look at the Browse deployment - you will notice that a subset of the your microservices will be included and defined in the respective pom.xml.

2. Because a specific subset of the services are composed together for a particular deployment, we need to configure the properties that apply to each service when bundled together. 

For example, the Browse deployment contains: "asset", "catalog", "campaign" etc... - in application-default.yml we will define the datasources for each of these as well as configure any applicable routes as necessary.

catalogbrowse:
  catalogprovider:
    url: 'https://localhost:9447' -> port 9447 is the default port configured for the Browse flex package
  catalogsearchprovider:
    url: 'https://localhost:9457' -> port 9457 is the default port configured for the Supporting flex package (which includes search)

3. Now that we have all our dependencies and the appropriate spring configuration needed for each service to function in a Flex Package, we can build a normal Spring Boot executable.

NOTE : In most cases, you will not be creating any other Java classes or code at the Flex Package level other than the main Spring Boot executable entry class. The /flexpackage projects are meant to build a specific "deployable" that comprise various underlying service dependencies + additional configuration (e.g. application.yml) that allows each service to function inside a Flex Package

4. Each Flex Package also contains a sample dockerfile that shows how to containerize the flex package Spring Boot application

5. Note that in the "Minimum Deployment" Flex Package configuration, we include all "demo-*-services.jar" except for the "indexer". We recommend that in the "min" deployment, you run indexer separately in a standalone fashion.