DEV Community: Aurimas Dainius

Architecture Decision Records

Aurimas Dainius — Mon, 19 May 2025 07:24:20 +0000

"Why did we choose this framework again?" - a question heard too often in development teams.

When working on complex projects, architectural decisions can quickly be forgotten or misunderstood.

Even decisions made just months ago can become unclear without proper documentation.

Archtecture Decision Records, or ADRs solve this problem by capturing the context and consequences of architectural choices. Each record documents:

The specific architectural decision.
The context and the problems it addresses.
The consequences and trade-offs considered.
The current status of the decision.

I've found ADRs particularly valuable when onboarding new team members or revisiting old projects.

They provide clear insights into why certain choices were made and help prevent the same discussions from happening repeatedly.

The best part about ADRs is their simplicity. A basic template, version control, and consistent updates are all you need.

They don't require complex tools or extensive documentation processes.

💡 While ADRs might seem like extra work initially, they can save a team countless hours of discussions and prevent many misunderstandings about architectural choices.

If you're not using ADRs yet, I strongly recommend trying them out.

Your future self (or your colleagues) will thank you. 📝

https://adr.github.io/ad-practices/ is a nice resource that gathers info from multiple different sources. Great if you'd like to learn more.
Otherwise, just registering the 4 key info points listed above is enough to get started.

How can you make sure you are implementing the right software?

Aurimas Dainius — Tue, 29 Apr 2025 12:17:17 +0000

I've found one of the best ways is to use Domain-Driven Design (DDD) - a software development approach that emphasizes close collaboration between business and developers through a common language that both can understand.

Here are the main benefits of DDD:
1️⃣ Shared Language: Using ubiquitous language eliminates translation between business and technical terms. Practically this means not using terminology in your business logic code that a business person would not be able to understand.
2️⃣ Business-Centric Models: DDD forces developers to model software around business concepts.
3️⃣ Clear Boundaries: Defining bounded contexts helps organize large systems into manageable pieces and identify parts that can become their own product or identify non-core domains that can be bought elsewhere instead of developing in-house.

However, DDD is not mainstream at all in the software community, in a large part I think due to deeply-engrained organizational practices that create silos between devs and business.

The real value of DDD isn't in its technical patterns but in how it structures communication.

When business stakeholders can read your business logic code and understand the behaviour, you're probably on the right track.

Two great books to learn more:

Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans, the author of DDD. This is more of an all-rounder introduction.
Implementing Domain-Driven Design by Vaughn Vernon. This is more of a practical guide with many code samples and patterns.

Why do software projects fail despite having excellent code?

Aurimas Dainius — Thu, 24 Apr 2025 06:58:39 +0000

It's concerning how many developers obsess over code quality while missing the fundamental question: are we building what users actually need?

Most of us have seen projects where teams spent weeks perfecting their architecture, choosing the latest frameworks, and arguing over the smallest of details on a pull request - only to deliver features that users never use. 🚫 This happens because we often jump straight into implementation without properly understanding the business requirements.

Here's a typical scenario:
Developer: "I've implemented a complex caching system to improve performance by X%"
User: "But I need the system to handle multiple currencies, not faster loading times"

The solution?

Start with workshops with BOTH your business and devs. 🤝
Use techniques like Event Storming or Domain Storytelling to make sure everyone is on the same page. 📝
Implement a system with 0 latency feedback loops - anyone should be able to send a screenshot to the business and ask their take. 🔄

Typically, teams spend a tiny minority of the whole project time on the things above, whereas it should take a good chunk of total project time.

Technical excellence matters, but it should come after ensuring we're building the right solution.

Final food for thought: A perfectly coded wrong solution is still wrong. 🤷‍♂️

Developers should have been replaced a long time ago. 🤔

Aurimas Dainius — Tue, 15 Apr 2025 06:55:43 +0000

Or at least this was widely believed when each big innovation came out.
The fantastic article lists 10 such waves that should have replaced us, including:
1️⃣ High level languages.
2️⃣ The Internet.
3️⃣ Low-code/No-code.

Each of them changed development, even in my 10-year career I've lived through several such waves, and the number of software developers in the world kept increasing regardless.

GenAI is the current wave. We see big claims (mostly from CTOs and business managers) about AI replacing developers. It makes sense for them to increase the hype, as they care about cost savings.

Developers care about usability though, and when AI tools become advanced enough to accelerate development and all the processes involved (requirements, testing, documentation, architecture, etc...), more and more software will be produced, therefore increasing demand for developers.

The best way to prepare for such shifts rests the same as it has always been - continuous learning, not staying too long in the comfort zone, and making everyone around you better. 📈 📖

From Code to Cloud: A Deep Dive into Mendix Deployments - Part 3: Private Cloud

Aurimas Dainius — Tue, 01 Apr 2025 10:37:19 +0000

In the 1st part of the series we have presented the various ways you can deploy a Mendix application. If you haven't read it yet, it will be a good primer for the whole series.

In this article we'll explore Private Cloud deployments.

What is Private Cloud?

Private Cloud means using cloud-native technologies (e.g. Docker, Kubernetes) on an infrastructure that you control.
It does not have to be physically on your servers, but you need access to create and remove resources.

For the purposes of Mendix, this will mean a Kubernetes or OpenShift cluster provided by one of the supported providers.

The Kubernetes pod you deploy will contain what was described in the on-premise overview article.

From the image above, you can see that you have a lot of control with Private Cloud.
Let's list some advantages:

You can decide where to physically host your cluster.
You decide how it will be accessed.
Control how deployments will work.
Decide your security constraints, how to protect it from outside threats.

Naturally, there are drawbacks:

You need to have the hardware to host your cluster.
You need to have the know-how of how to configure all of that.
You need to implement security, load-balancing, deployments, ci/cd, etc...

Whether it's right for you will depend on many organizational, technical, functional constraints. If you haven't decided yet, check out the previous blog post.

There are actually 2 versions of the Private Cloud.

Connected mode

In connected mode, you can manage many aspects of your app through the Mendix Portal.

For example:

Change constants' values.
Add JVM arguments.
Increase the nr of replicas of your app.
Change the admin password.
Change log levels.
etc...

One caveat here is that you will need to whitelist some urls from your cluster so that Mendix (the gateway agent specifically) can communicate with its external portal and vice-versa. Details here.

Standalone mode

In standalone mode, you only interact with your cluster directly, you don't have any control panel to manage it through the Mendix Portal.

How to deploy

There are a few steps to this process:

Register a new cluster in the Mendix Portal.
Add a namespace where you will deploy your app.
Install the mendix operator inside your namespace.
Deploy your app into that cluster and namespace.

Register a new cluster

This does not mean actually creating the cluster in Kubernetes. You must create a cluster yourself in whichever K8s (or OpenShift) provider and then just tell the Mendix Portal that it exists.

Add a namespace

Next you need to register a namespace where your app will live.

Install the Mendix operator

Once you've done with the cluster registration, you will get a link to download the Mendix operator.

Mendix operator

This operator is a separate pod that runs in your namespace. It is a Kubernetes Operator that monitors pod/pods of your Mendix app.

Whenever you update something through the Mendix Portal (a jvm argument, the app version, etc...), the operator receives this new information and applies the necessary changes to your app's pod.

The operator itself can be configured with the mxpc-cli script. This script produces a yaml file with custom resources which contain the operator's configuration.

To install it, you'll run a command like:

./mxpc-cli installer -n <your namespace> -i <namespace uid> -s <secret>

Once installed you can either use the non-interactive mode and configure it via commands, or use the interactive mode and configure it using a UI

This utility also allows you to do other things, here's the help message from it:

Once configured, the operator will establish a connection to your database, storage, registry to confirm that the configuration is correct.

The configuration of the operator and your app is saved in custom K8S resources: OperatorConfiguration, MendixApp, ...

You can of course inspect them:

kubectl get OperatorConfiguration -n test -oyaml | less

apiVersion: v1
items:
- apiVersion: privatecloud.mendix.com/v1alpha1
  kind: OperatorConfiguration
  metadata:
    annotations: ...
    name: mendix-operator-configuration
    namespace: test
  spec:
    baseOSImageTagTemplate: ubi8-1-jre{{.JavaVersion}}-entrypoint
    buildResources:
      limits:
        cpu: "1"
        memory: 256Mi
      requests:
        cpu: 250m
        memory: 64Mi
    endpoint:
      ingress:
        annotations:
          nginx.ingress.kubernetes.io/proxy-body-size: 500m
        domain: 192.168.49.2.nip.io
        enableTLS: true
        ingressClassName: public
        path: /*
      type: ingress
    ...
...

This means you could also save this yaml in your gitops repository, version it, template it, and use for future deployments even without the mxpc-cli utility.

Deploy the app

Now you can finally deploy your app to this cluster. You need to go to your app's page in the Mendix Portal, the environments section.

You need to create the environment. This allows you to create environments that are connected with different namespaces or even different clusters.

Once created, just deploy your app to that cluster.

The following will happen next:

The Mendix operator will receive the instructions to deploy the app.
It's going to start a worker pod to build a docker image of your app.
It will launch a pod based on the image produced just before.

You will then be able to see your app's releases and all configured environments from this page:

This page allows you to deploy a release to the environment of your choosing. Typically, you will have at least a dev and a production environment, but you can adapt it to your needs.

Supported providers

As of 01 Apr 2025, the following providers or flavours of k8s are supported.

Conclusion

This was not meant to be a full guide on how to do a private-cloud deployment, as there is too much information to cover in just one article. Instead, it's meant to give an overview of what it means, what you can do with it, and why you would want to deploy to a private cloud in the first place.
For a guide with more instructions I would still refer to the official Mendix documentation but know that sometimes it's not easy to understand everything written there, from my experience.

Hopefully this gives you more information and motivation to use it with your Mendix applications.
I will do separate articles on more detailed subjects, like: difference between connected and standalone environments, how to segregate your environments from each other, more details on the mendix operator, how to integrate a CI/CD pipeline, etc...

If you'd like more information, or need some help in setting up your deployments, don't hesitate to reach out.

From Code to Cloud: A Deep Dive into Mendix Deployments - Part 2: On-Premise

Aurimas Dainius — Thu, 20 Mar 2025 09:41:36 +0000

In the 1st part of the series we have presented the various ways you can deploy a Mendix application. If you haven't read it yet, it will be a good primer for the whole series.

We'll start by exploring on-premise deployments.

Why on-premise first?

Mainly it's because on-premise is the lowest level we can go to, meaning the web server and application level. This can help us learn what building blocks the application is made of and what it actually is.

What does on-premise mean?

An essential question to answer. With Mendix, you can consider on-premise any deployment on your own infrastructure that is generally not running Kubernetes or OpenShift and not using a Mendix Operator.
If you use them, we'd be talking about a Private Cloud deployment.

Mendix application dissected

To be able to deploy a Mendix application, it will be good for us to understand the technology behind.

Mendix applications are based on JVM: when you click 'Run' in Mendix Studio Pro, it will collect all the microflows, constants, even entities, and build them into an executable java application. (how that's done is interesting as well but it's better to leave that for another article)

This application can then be run as any other java application would be.
If we were to ssh into a Mendix application pod (or just a docker container), you'd see exactly a java process:

cat /proc/29/cmdline
/opt/mendix/build/.local/bin/java -Dfile.encoding=UTF-8 -Djava.io.tmpdir=/opt/mendix/build/data/tmp -XX:OnError=kill -s USR1 7 -XX:OnOutOfMemoryError=kill -s USR2 7 -DapplicationName=docker_example -XX:MaxMetaspaceSize=256M -Xmx512M -Xms512M -XX:+UseSerialGC -DMX_INSTALL_PATH=/opt/mendix/build/runtimes/10.20.0.60519 -jar /opt/mendix/build/runtimes/10.20.0.60519/runtime/launcher/runtimelauncher.jar /opt/mendix/build/

The last argument /opt/mendix/build/ of the command contains our whole application on the container (example app below called NoTicket):

ls /opt/mendix/build/web/pages/en_US/NoTicket/
Ticket_NewEdit.page.xml      Ticket_NewEdit.page.xml.gz   Ticket_Overview.page.xml     Ticket_Overview.page.xml.gz

ls /opt/mendix/build/model/
bundles/           dependencies.json  i18n/              lib/               metadata.json      microflows.json    model.mdp          operations.json    resources/

From this we can learn that it's basically a jar of the mendix runtime that runs a folder which contains our application's compiled code (the jvm bytecode) and the resources it needs (.js, .css files, pages in .xml format, etc...). When you build your app, it is packaged into an .mda file which is basically an archive of your application.

Does that sound familiar? If you're coming from Java EE (or Jakarta EE) background, this might make you think immediately of an application server like Tomcat.

And you would be right, Mendix Runtime is actually an equivalent of an application server like Tomcat. Here's a representation on what it contains:

The HTTP server you see in the image uses Jetty as a library to handle http requests but it does not itself implement the Jakarta Servlet API. Hence, you cannot build a mendix application and deploy on a Tomcat, or deploy any other Java application on a Mendix Runtime.

How to deploy on premise

We have a few options to deploy on premise:

Deploy on Linux as a Java process using m2ee-tools python utility.
Deploy on a Microsoft IIS server.
Deploy wherever you want using Docker (best solution in my view).

Mendix prides itself on being cloud-native out-of-the-box, and we should benefit from that as much as possible. While you can containerize any application in theory, with Mendix that's already taken care of - just build your image and deploy.
Therefore, I will only focus on the last option, using Docker. It has many advantages:

It's better both for you and your system admin as you can isolate your app's environment from the machine it's running on.
It bundles the app into a neat package that can be run on any machine.
It's easy to split the build and deploy processes.
Devs can modify the image to include any supporting processes in the container.

To build the app, we will use docker-mendix-buildpack. It will collect your application files, produce an .mda package, and build a docker image.

You can follow these steps:

Clone docker-mendix-buildpack:

git clone https://github.com/mendix/docker-mendix-buildpack
cd docker-mendix-buildpack

Clone your app's repo where you want to build it (you can get the git link from the Team Server section of your app in Mendix Portal):

git clone https://git.api.mendix.com/xxxx-yyyy-zzzz-yyyy.git

Build your image:

docker build --build-arg BUILD_PATH=appFolder --tag mendix/mendix-appName:deploy .

On the 1st run, it's going to build some helper images, so it will take some time. On next runs it's going to be much faster.
Once you've done that, you can either run the image, or push it to your company's container registry if you have a different build and runtime server.
If it's a release version, make sure to give it a version (like 1.1.0 instead of a snapshot version like deploy).

To start it, simply run the docker image:

docker run -it \
  -e ADMIN_PASSWORD=Password1! \
  -e DATABASE_ENDPOINT=postgres://username:password@host:port/mendix \
  mendix/mendix-appName:deploy

How you can use it as part of you CI/CD process

You can easily automate the process with a simple bash script, integrate into a build tool like Jenkins, or Github Actions, Gitlab Workflows, etc...

docker compose

I also like to use docker-compose to quickly deploy a database alongside the app container. This way I can build and deploy a fully-functioning app in minutes.
Here's a sample script for reference:

---
version: "3.0"
networks:
  mendix-network:
    driver: bridge
services:
  postgres:
    image: postgres
    hostname: postgres
    container_name: postgres
    restart: always
    shm_size: 128mb
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: mendix
      POSTGRES_DB: mendix
    volumes:
      - postgres-db:/var/lib/postgresql/data
    networks:
      - mendix-network
  mendix:
    image: mendix/mendix-appName:deploy
    hostname: appName
    container_name: appName
    ports:
      - "8080:8080"
    environment:
      ADMIN_PASSWORD: "some great password"
      DATABASE_ENDPOINT: postgres://mendix:postgres@postgres:5432/mendix
      mem_limit: 500m
    restart: always
    depends_on: [postgres]
    networks:
      - mendix-network

volumes:
  postgres-db:

Then you can simply run:

docker compose up -d
docker logs appName --follow

Kubernetes

Technically, once you have build a docker image (or an image in OCI format), you can just run it in your kubernetes cluster. Normally with Mendix though, you would use a Mendix Operator which would build the app and the image for you and start your app. This would all take place inside your cluster. It will be covered much more in depth in an upcoming article.

Conclusion

Mendix makes it easy to deploy cloud-native applications on your infrastructure. Using the docker-mendix-buildpack you can easily produce a docker image with your application, and deploy it wherever you want.

While on-premise deployments are not always the best option, they can be great for small applications, demos, proof of concepts, or if the client's infrastructure does not support Kubernetes or OpenShift deployments.

Hopefully, this information will help you understand the behind-the-scenes processes of a Mendix app build and deployment, aiding in debugging any deployment issues regardless of the chosen deployment option.
If you'd like more information, or need some help in setting up your deployments, don't hesitate to reach out.

From Code to Cloud: A Deep Dive into Mendix Deployments - Part 1

Aurimas Dainius — Mon, 24 Feb 2025 13:44:21 +0000

This article will begin a multiple-part series on Mendix deployments. Building applications quickly and easily with Mendix is awesome, but those applications eventually need to run on some hardware.

We're going to see how much flexibility Mendix provides based on your unique needs and capabilities.

Deployment options

With Mendix, you have 3 main options for deploying your applications.
Here they are ordered by convenience and amount of control:

As you can see from the very professional image above, Mendix Cloud is the most convenient option, but offers the least control.

On-premise deployments, on the other end, offer least convenience, but allow for extreme levels of control.

Let's quickly recap each one.

Mendix Cloud

The easiest option. You must estimate how many resources your app is going to need, and select a cloud resource pack suitable for your needs.

Mostly everything then will be setup for you as you can see in the simplified image above.

With this option, you have the following advantages:

Ease of setup. Select your resource pack and deploy.
Out-of-the box tools for your app's lifecycle: monitoring, auditing, firewall, backups, etc...
Ensured availability based on your subscription plan.
You can choose the region where you want your app to be hosted.

There are some drawbacks (if you can call them that):

Cost. This is an obvious one - if you don't host your application, it has to be hosted somewhere, so you must pay for those resources. However, cost is a complex subject, you need to evaluate a lot of criteria, like what skills your team possesses (and their cost in turn), how much time you're willing to spend on the operational part (which costs too), etc...
You have less control over the application. This is logical - if you run something on your server, you can customize it any way you want. With a public cloud, you have much fewer options.

Mendix Private Cloud

Private Cloud means you host your mendix application on cloud resources that you own and directly pay for.
This can be a kubernetes cluster on a cloud provider like AWS, Google Cloud Platform, or Azure.

It can also mean a kubernetes cluster on a local instance of MicroK8s, Kind, or any other local kubernetes setup.

You also have the option to deploy an app on an OpenShift cluster.

Private Cloud is great if your organization already has a cluster that you can use, or have strict compliance and security standards which might restrict you from using any publicly-provided Cloud setups that you don't control yourself.

With Private Cloud, you are free to choose your own provider, implement your own security policies, setup your own monitoring, backup, other tools.

Cost is likely to be lower, especially if you have a skilled DevOps team who can install the mendix app in your cluster, configure the needed tools, and maintain it in the long run.

On-premise

Lastly we have on-premise deployments.
On-premise is the old school 'it works on my machine' way.

In practice, you would probably have a bare metal server inside your company or provided by a hosting provider.
You'd run a mendix app either as:

A java process directly on the server.
A process inside a MS Internet Information Services (IIS) server.
A docker container on your server.

Obviously, if you have to go the on-premise way, I'd go with docker for better isolation of both your app and your server.

With these deployments you will certainly have the most control, but also the most hassle as you'll have to setup everything yourself.

For some small use cases where you don't need a kubernetes cluster but you can't use the Mendix Cloud due to compliance/security constraints, this will be the only option.

Conclusion

Mendix provides a lot of flexibility on how to deploy your application. When you have to make a decision, consult their in-depth decision guide to make the best decision for your use case.
You'll have to take many elements into account - regulatory, security circumstances you have, the technical skills and composition of your team, your current DevOps maturity, your budget, etc...

If you'd like to learn more, head over to the Mendix documentation and stay tuned for upcoming articles. Each of these deployment options will get a deep dive of its own in the next weeks.

Converting a Spring MVC App To Mendix

Aurimas Dainius — Wed, 05 Feb 2025 18:28:03 +0000

This is a followup to this post about JPA entity export from Java to Mendix.

Last time we saw how, given a Java Spring application, we can read it's metadata and 'recreate' it in a Mendix application. We detected JPA entities (based on @Entity annotation), exported them to a custom json schema, and finally imported everything to Mendix using their Platform SDK.

Now we're going to see how to convert another essential part of a Java Spring app - the REST layer.

Sample Spring MVC app

Our sample uses the Spring MVC framework, but similar logic could be applied to Jersey or any other framework.

It has only one controller: the CatController (what did you think it was going to be? :P)

@RestController
@RequestMapping(path = "/cat", consumes = "application/json", produces = "application/json")
public class CatController {
    private final CatService catService;

    public CatController(CatService catService) {
        this.catService = catService;
    }

    @GetMapping
    public List<CatDto> allCats() {
        return catService.getCats();
    }
}

The controller is exposed under path /cat and it produces json when called with GET. It will return a list of all cats in our database.

Here are the objects we will have to convert between Java and Mendix:

Spring MVC application -> would be a published REST service in Mendix.
Spring MVC controller -> a resource in a published REST service.
A method corresponding to a REST endpoint -> an operation in a Mendix resource.

Extracting controllers into json

Same as in the last article, we will be using reflection to detect controllers and api endpoints at runtime. You can see other possible alternatives pondered in the last post.

Here's the code that gathers all this info:

public static void exportRESTLayerTo(String filePath) throws IOException {
    AnnotatedTypeScanner typeScanner = new AnnotatedTypeScanner(false, RestController.class);

    Set<Class<?>> restControllerClasses = typeScanner.findTypes(JavaToMendixApplication.class.getPackageName());
    log.info("Controller classes are: {}", restControllerClasses);

    List<MendixPublishedRestService> mendixRestServices = new ArrayList<>();
    List<MendixPublishedRestServiceResource> mendixResources = new ArrayList<>();

    for (Class<?> restControllerClass : restControllerClasses) {
        List<MendixPublishedRestServiceOperation> mendixOperations = new ArrayList<>();
        for (Method method : restControllerClass.getDeclaredMethods()) {
            if (!Modifier.isPublic(method.getModifiers())) {
                continue;
            }
            Optional<MendixPublishedRestServiceOperation> restOperation = findRestOperation(
                    method.getAnnotations());
            restOperation.ifPresent(op -> mendixOperations.add(op));
        }

        MendixPublishedRestServiceResource newResource = new MendixPublishedRestServiceResource(
                retrieveControllerPath(restControllerClass), mendixOperations);
        mendixResources.add(newResource);
    }
    ...
}

We begin by finding all classes annotated with @RestController.

Then, for each controller, we:

Get the path specified in the path field of the annotation. This path will also become the name of the mendix resource.
We will then retrieve controller methods that correspond to our endpoints.

To find the right controller methods, we just need to pick public methods and check if their annotations correspond to any of the following Spring MVC endpoint annotations:

private static final Map<Class<?>, RestOperation> JAVA_TO_MENDIX_REST_OPERATION = Map.ofEntries(
        Map.entry(GetMapping.class, RestOperation.GET),
        Map.entry(PostMapping.class, RestOperation.POST),
        Map.entry(PutMapping.class, RestOperation.PUT),
        Map.entry(DeleteMapping.class, RestOperation.DELETE)
);

For each such endpoint method we find, we will add it to the list of operations in the MendixPublishedRestServiceResource object.
For simplicity's sake we only do a basic mapping of the endpoints, but we could go deeper and also export path params, request body, headers, etc...

Finally, we create a MendixPublishedRestService object to contain our rest controller and export to a json file:

mendixRestServices.add(new MendixPublishedRestService("JavaToMendixApplication", "api", "1", mendixResources));
writeToJsonFile(filePath, mendixRestServices);

Here are all the classes we used for the export:

record MendixPublishedRestService(
    String serviceName, 
    String path, 
    String version, 
    List<MendixPublishedRestServiceResource> resources) {
}

record MendixPublishedRestServiceResource(
    String name, 
    List<MendixPublishedRestServiceOperation> operations) {
}

record MendixPublishedRestServiceOperation(
    String path, 
    RestOperation restOperation) {

    enum RestOperation {
        GET,
        POST,
        PUT,
        DELETE
    }
}

Importing rest services into Mendix

Now we're going to use Mendix's Platform SDK which has a Typescript API to interact with it.

First we'll create some objects to represent our services and controllers:

interface ImportedRestService {
    serviceName: string;
    path: string;
    version: string;
    resources: ImportedRestResource[];
}

interface ImportedRestResource {
    name: string;
    operations: ImportedRestOperation[];
}

interface ImportedRestOperation {
    path: string;
    restOperation: string;
}

Then we are going to create a working copy of our Mendix app:

const client = new MendixPlatformClient();
const app = await client.getApp(appId);

const workingCopy = await app.createTemporaryWorkingCopy("main");
const model = await workingCopy.openModel();

const module = model.allModules().filter(m => m.name === "MyFirstModule")[0];

The SDK will actually pull our mendix app from git and work on that.

After reading from the json file, we will loop the services.

First we create a PublishedRestService first in our MyFirstModule module.
We give it a name, version, and base path (in our case, api):

importedServices.forEach(importedService => {
    const restService = rest.PublishedRestService.createIn(module);
    restService.serviceName = importedService.serviceName;
    restService.path = importedService.path;
    restService.version = importedService.version;
    restService.name = importedService.serviceName;
    ...
});

We then loop the resources in that service and create a PublishedRestServiceResource with a name (which will also be a path for that resource):

importedService.resources.forEach(importedResource => {
    const publishedRestResource = rest.PublishedRestServiceResource.createIn(restService);
    publishedRestResource.name = importedResource.name;
    ...
});

Finally, we get the operations for each resource. Operations could have their own path, which will be appended to the service and resource path. We also assign an http method and create a sample microflow for that operation so that we have something to work with once the import is complete:

importedResource.operations.forEach(op => {
    const publishedRestOperation = rest.PublishedRestServiceOperation.createIn(publishedRestResource);
    publishedRestOperation.path = op.path;
    publishedRestOperation.httpMethod = getMendixHttpMethod(op.restOperation);

    assignSampleMicroflowToOperation(module, importedResource, op, publishedRestOperation);
});

The Mendix Platform SDK will create the service in its local working copy of our mendix application. Now we just need to tell it to commit the changes:

async function commitChanges(model: IModel, workingCopy: OnlineWorkingCopy, entitiesFile: string, servicesFile: string) {
    await model.flushChanges();
    await workingCopy.commitToRepository("main", 
        { commitMessage: `Imported DB entities from ${entitiesFile} and REST services from ${servicesFile}` }
    );
}

After a few seconds, you can open the app in Mendix Studio Pro and verify the results:

Our published rest service has been created and we can start working on the microflows behind each endpoint.

If you'd like to experiment yourself or see the full code, head over to this repo.

Ideas for the future

Improve documentation of the Mendix Platform SDK. There is a lack of user guides and often documentation on what various objects represent. My last articles were meant to mitigate this issue.
The examples are in Java but the same concepts can be applied for any language.
One day I'll make a full library out of this and try to use static code analysis instead of runtime analysis to 'export' the Java app as it will be more convenient for the user.

Conclusion

The Mendix Platform SDK is a powerful feature allowing to interact with the mendix app programmatically. We can export entire apps to mendix, although the business logic part will require more effort.

Mendix list some sample use cases like importing/exporting code, analyzing app complexity, etc...

Have a look at them in case you are interested.

For this article, you can find the full code here.

Converting JPA entities to Mendix

Aurimas Dainius — Mon, 13 Jan 2025 08:07:28 +0000

Recently while exploring Mendix, I've noticed they had a Platform SDK which allows you to interact with the mendix app model through an API.

This gave me an idea to explore if it can be used to create our domain model. Specifically, to create a domain model based on an existing traditional application.

If generalized further, this could be used to convert any existing application into Mendix and continue development from there.

Converting a Java/Spring web application to Mendix

So, I created a small Java/Spring web application with a simple API and database layer. It uses an embedded H2 database for simplicity.

In this post, we are only going to be converting JPA entities. Let's take a look at them:

@Entity
@Table(name = "CAT")
class Cat {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    private String name;
    private int age;
    private String color;

    @OneToOne
    private Human humanPuppet;

    ... constructor ...
    ... getters ...
}

@Entity
@Table(name = "HUMAN")
public class Human {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    private String name;

    ... constructor ...
    ... getters ...
}

As you can see they are quite simple: a Cat with a name, age, color, and its Human puppet, since cats rule the world as we know.

Both of them have an auto-generated ID field. Cat has a one-to-one association with a Human so that it can call its human whenever it wants. (If it wasn't a JPA entity I would have put a meow() method but let's leave that for the future).

The app is fully functioning but right now we're only interested in the data layer.

Extracting Entity metadata in json

This can be done in a few different ways:

By statically analyzing entities in their package.
By using reflection to read those entities at runtime.

I've opted for option 2 because it's quicker and I couldn't easily find a library that can do option 1.

Next, we need to decide how to expose json once we build it. To make things simple, we'll just write it into a file. Some alternative ways could be:

Exposing it through an api. This is more complicated as you also need to ensure that endpoint is secured very well as we must not expose our metadata publicly.
Exposing it through some management tool, like spring boot actuator, or jmx. It's safer, but still takes time to setup.

Let's now see the actual code:

public class MendixExporter {
    public static void exportEntitiesTo(String filePath) throws IOException {
        AnnotatedTypeScanner typeScanner = new AnnotatedTypeScanner(false, Entity.class);

        Set<Class<?>> entityClasses = typeScanner.findTypes(JavaToMendixApplication.class.getPackageName());
        log.info("Entity classes are: {}", entityClasses);

        List<MendixEntity> mendixEntities = new ArrayList<>();

        for (Class<?> entityClass : entityClasses) {
            List<MendixAttribute> attributes = new ArrayList<>();
            for (Field field : entityClass.getDeclaredFields()) {

                AttributeType attributeType = determineAttributeType(field);
                AssociationType associationType = determineAssociationType(field, attributeType);
                String associationEntityType = determineAssociationEntityType(field, attributeType);

                attributes.add(
                        new MendixAttribute(field.getName(), attributeType, associationType, associationEntityType));
            }
            MendixEntity newEntity = new MendixEntity(entityClass.getSimpleName(), attributes);
            mendixEntities.add(newEntity);
        }

        writeToJsonFile(filePath, mendixEntities);
    }
    ...
}

We start with finding all classes in our app marked with JPA's @Entity annotation.
Then, for each class, we:

Get the declared fields with entityClass.getDeclaredFields().
Loop each field of that class.

For each field then, we:

Determine the attribute's type:

private static final Map<Class<?>, AttributeType> JAVA_TO_MENDIX_TYPE = Map.ofEntries(
        Map.entry(String.class, AttributeType.STRING),
        Map.entry(Integer.class, AttributeType.INTEGER),
        ...
        );
// we return AttributeType.ENTITY if we cannot map to anything else

Essentially we just match the java type with our custom enum values by looking them up in JAVA_TO_MENDIX_TYPE map.

Next, we check if this attribute is actually an association (points to another @Entity). If so, we determine the type of an association it is: one-to-one, one-to-many, many-to-many:
```
private static AssociationType determineAssociationType(Field field, AttributeType attributeType) {
    if (!attributeType.equals(AttributeType.ENTITY))
        return null;
    if (field.getType().equals(List.class)) {
        return AssociationType.ONE_TO_MANY;
    } else {
        return AssociationType.ONE_TO_ONE;
    }
}
```
To do that, we just check the previously mapped attribute type. In case it's Entity, which just means that in the step before we couldn't map it to any primitive java type, String, or Enum.
Then we also need to decide what kind of association it is. The check is simple: if it's a List type, then it's a one-to-many, otherwise one-to-one (did not implement 'many-to-many' yet).
We then create a MendixAttribute object for each field found.

Once that is done, we just create a MendixEntity object for the entity with a list of attributes assigned.
MendixEntity and MendixAttribute are classes we will use to map to json later:

public record MendixEntity(
        String name,
        List<MendixAttribute> attributes) {
}

public record MendixAttribute(
        String name,
        AttributeType type,
        AssociationType associationType,
        String entityType) {

    public enum AttributeType {
        STRING,
        INTEGER,
        DECIMAL,
        AUTO_NUMBER,
        BOOLEAN,
        ENUM,
        ENTITY;
    }

    public enum AssociationType {
        ONE_TO_ONE,
        ONE_TO_MANY
    }
}

Finally, we save a List<MendixEntity> to a json file using jackson.

Importing entities into Mendix

Here comes the fun part, how do we read the json file we generated above and create mendix entities from it?

Mendix's Platform SDK has a Typescript API to interact with it.
First we will create objects to represent our entities and attributes, as well as enums for association and attribute types:

interface ImportedEntity {
    name: string;
    generalization: string;
    attributes: ImportedAttribute[];
}

interface ImportedAttribute {
    name: string;
    type: ImportedAttributeType;
    entityType: string;
    associationType: ImportedAssociationType;
}

enum ImportedAssociationType {
    ONE_TO_ONE = "ONE_TO_ONE",
    ONE_TO_MANY = "ONE_TO_MANY"
}

enum ImportedAttributeType {
    INTEGER = "INTEGER",
    STRING = "STRING",
    DECIMAL = "DECIMAL",
    AUTO_NUMBER = "AUTO_NUMBER",
    BOOLEAN = "BOOLEAN",
    ENUM = "ENUM",
    ENTITY = "ENTITY"
}

Next, we need to get our app with an appId, create a temporary working copy, open the model, and find the domain model we are interested in:

const client = new MendixPlatformClient();
const app = await client.getApp(appId);
const workingCopy = await app.createTemporaryWorkingCopy("main");
const model = await workingCopy.openModel();
const domainModelInterface = model.allDomainModels().filter(dm => dm.containerAsModule.name === MyFirstModule")[0];
const domainModel = await domainModelInterface.load();

The SDK will actually pull our mendix app from git and work on that.

After reading from the json file, we will loop the entities:

function createMendixEntities(domainModel: domainmodels.DomainModel, entitiesInJson: any) {
    const importedEntities: ImportedEntity[] = JSON.parse(entitiesInJson);

    importedEntities.forEach((importedEntity, i) => {
        const mendixEntity = domainmodels.Entity.createIn(domainModel);
        mendixEntity.name = importedEntity.name;

        processAttributes(importedEntity, mendixEntity);
    });

    importedEntities.forEach(importedEntity => {
        const mendixParentEntity = domainModel.entities.find(e => e.name === importedEntity.name) as domainmodels.Entity;
        processAssociations(importedEntity, domainModel, mendixParentEntity);
    });
}

Here we use domainmodels.Entity.createIn(domainModel); to create a new entity in our domain model and assign a name to it. We can assign more properties, like documentation, indexes, even location where the entity will be rendered in the domain model.

We process the attributes in a separate function:

function processAttributes(importedEntity: ImportedEntity, mendixEntity: domainmodels.Entity) {
    importedEntity.attributes.filter(a => a.type !== ImportedAttributeType.ENTITY).forEach(a => {
        const mendixAttribute = domainmodels.Attribute.createIn(mendixEntity);
        mendixAttribute.name = capitalize(getAttributeName(a.name, importedEntity));
        mendixAttribute.type = assignAttributeType(a.type, mendixAttribute);
    });
}

The only thing here we have to put some effort in is to map the attribute type to a valid mendix type.

Next we process the associations. Firstly, since in our Java entities associations were declared by a field, we need to distinguish which fields are simple attributes, and which are associations. To do that we just need to check if it's an ENTITY type or a primitive type:

importedEntity.attributes.filter(a => a.type === ImportedAttributeType.ENTITY) ...

Let's create the associations:

const mendixAssociation = domainmodels.Association.createIn(domainModel);

const mendixChildEntity = domainModel.entities.find(e => e.name === a.entityType) as domainmodelsEntity;
mendixAssociation.name = `${mendixParentEntity?.name}_${mendixChildEntity?.name}`;
mendixAssociation.parent = mendixParentEntity;
mendixAssociation.child = mendixChildEntity;

mendixAssociation.type = a.associationType === ImportedAssociationType.ONE_TO_ONE || a.associationType === ImportedAssociationType.ONE_TO_MANY ?
    domainmodels.AssociationType.Reference : domainmodels.AssociationType.ReferenceSet;
mendixAssocation.owner = a.associationType === ImportedAssociationType.ONE_TO_ONE ? domainmodelsAssociationOwner.Both : domainmodels.AssociationOwner.Default;

We have 4 important properties to set, besides the name:

The parent entity. This is the current entity.
The child entity. In the last step, we created mendix entities for each java entity. Now we just need to find the matching entity based on the type of the java field in our entity:
```
domainModel.entities.find(e => e.name === a.entityType) as domainmodelsEntity;
```
Association type. If it's one-to-one, it maps to a Reference. If it's one-to-many, it maps to a Reference Set. We will skip many-to-many for now.
The association owner. Both one-to-one and many-to-many associations have the same owner type: Both. For one-to-one, the owner type must be Default.

The Mendix Platform SDK will have created the entities in its local working copy of our mendix application. Now we just need to tell it to commit the changes:

async function commitChanges(model: IModel, workingCopy: OnlineWorkingCopy, entitiesFile: string) {
    await model.flushChanges();
    await workingCopy.commitToRepository("main", { commitMessage: `Imported DB entities from ${entitiesFile}` });
}

After a few seconds, you can open the app in Mendix Studio Pro and verify the results:

There you have it: a Cat and Human entity with a one-to-one association in between them.

If you'd like to experiment yourself or see the full code, head over to this repo.

Ideas for the future

In this example I've used a Java/Spring application to convert from since I'm most proficient in it but any application can be used. It's enough to just be able to read type data (statically or at runtime) to extract the class and field names.
I'm curious to try reading and exporting some java logic to Mendix microflows. We probably can't really convert the business logic itself but we should be able to get the structure of it (business method signatures at least?).
The code from this article could be generalized and made into a library: the json format can stay the same, and there could be one library to export java types, and another one to import mendix entities.
We could use the same approach to do the reverse: convert a mendix to another language.

Conclusion

The Mendix Platform SDK is a powerful feature allowing to interact with the mendix app programmatically. They list some sample use cases like importing/exporting code, analyzing app complexity.
Have a look at them in case you are interested.
For this article, you can find the full code here.

Collaborating with business using low-code development

Aurimas Dainius — Thu, 19 Dec 2024 10:40:20 +0000

Has it ever happened to you while coding that you either had to:

Draw a diagram before starting coding to put ideas into place and have a scheme of how a process should look like?
Have to draw a diagram to show to a business stakeholder so that you are able to more easily explain how a process works?

I bet you've faced at least one of those situations.

Lost in translation

There are a few problems caused by such scenarios:

The biggest one is that some information will inevitably be lost in translation. Some information will be lost in the intermediate step of drawing a diagram, whether you plan to write code from it later or you draw it based on existing code.
It takes time and energy to make a more visual model of what needs to be done.

How low-code can help

One of the biggest advantages of low-code development is visual programming where instead of writing text you drag and drop or draw elements that eventually do something you expect.

Let's consider the example below:

Are you able to deduce what is done in this flow? (called microflow in Mendix)

I would argue even a non-technical person will understand the gist of it.

We get the following benefits of visual programming in this case:

Both you and the more business-oriented person (but anyone can benefit from this really) will have a much more intuitive representation of a business process. And it's an actual piece of software that runs and is constantly evolving, not some document that stays hidden away in Confluence and eventually becomes obsolete.
It's quicker as we can understand drawings much faster than we can read text.
It's shared because the other person, even if they don't have a lot of technical skills, will be able to figure out more or less what they are seeing. It can also be used in meetings/presentations.
Less information will be lost in translation as there are simply fewer steps for information to travel.

There are some drawbacks too:

Poorly implemented microflows would still be difficult to understand.
Some training is still needed. Any visual programming tool still has a notation which, even if simple, requires at least minimal investment to understand.

Summary

It's a simple use case, but stacked up over time, over many interactions can add up to significantly less time used for such activities and likely producing better results due to less friction in knowledge sharing.

You still need to follow good programming practices with low-code:

Avoid microflows with too much stuff in it. Just like in normal programming, code that executes business logic should be quite clear to read and not overloaded with technical calls.
Don't be afraid of long variable/object names. This is descriptive and most of the time avoids the need for comments, which tend to not be updated as logic changes.

As low-code tooling continues to evolve, I feel like the gap between developer and business knowledge will grow ever smaller, benefiting everyone involved.

Getting used to visual software development

Aurimas Dainius — Tue, 10 Dec 2024 20:36:39 +0000

Recently I've started using a low-code platform Mendix to produce software.
I wasn't planning on it, but an opportunity presented itself and I was curious to learn more about this new (to me) thing.

And, to my surprise, I did like it.
Probably the biggest change is passing from writing actual lines of code in text, to visually constructing the software.

For UI, this is not weird at all, it's even much more pleasant than writing HTML/CSS/JavaScript.
For backend though, it's a different story.

How does it actually work?

Think about this: when you need to code something complex, you normally don't start writing code right away.
You think about it, draw something down on a whiteboard or a piece of paper, identify some patterns, and only then start coding.

With Mendix, the process feels very similar, except that the last 'coding' part is very different.

Here's how the process looks like in Mendix:

You create a new microflow. Microflows are where your business logic gets executed. I like to think of them as a method in a service class. You can call other microflows from within.
You drag and drop which elements you need to implement your logic. You will do the same things as you would in Java: create variables, retrieve stuff from the database, modify objects, loop collections, have conditional statements, etc...
At the end of the microflow, you might return something, or not return anything. You might commit an object to the DB, or signal to the client-side that a page should be closed.

Here are some activities you can add to a mendix microflow:

There are many more of them and you can even create your own.
There are hundreds more in the mendix marketplace to choose from.

And here's a sample microflow:

Here we simply retrieve an object from the database or create a new one if it doesn't exist.
It's quite neat and easy-to-understand, even for a non-technical person.

It could look something like this in Java:

public class SubscriptionService {
    // ...
    public SubscriptionCost getOrCreateSubscriptionCost(
        Subscription subscription,
        BillingFrequency billingFrequency
    ) {
        // implement getSubscriptionCost method somewhere, or use a spring data repository
        Optional<SubscriptionCost> existingCost = subscriptionRepository.getSubscriptionCost(billingFrequency.id(), subscription.id());

        return existingCost.orElseGet(() -> {
            SubscriptionCost newCost = new SubscriptionCost(subscription, billingFrequency, ...);
            subscriptionRepository.save(newCost);
            return newCost;
        });
    }
    // ...
}

They are both good, and both are visualizations of a process that happens in the real world.

Pros of visual development

You have a visual representation of the flow you are modelling, making things clearer without having to do drawings yourself without writing code.
The visual representation is the actual 'code', no need to convert it to something else yourself.
You can literally show the microflow to a business person and they are much more likely to understand drawings rather than code.
It is a much better documentation than just code.
You are likely to move faster. This is simply due to the fact that you are operating at a higher level of abstraction. If the flexibility of your platform is enough for you, you will be faster. If not, you might be blocked and have to spend time implementing code yourself to accomplish what you need.

Cons of visual development

As it is still an abstraction over regular code, inevitably you do lose some flexibility, same as what happens when passing from assembly to C or from C to Java.
Given that the 'visual' model needs to be translated to machine-runnable code, it will be slower to run. (though I suspect there are many optimizations in Mendix to make it as fast as possible)
As of 2024, low-code community is not that big compared to the big programming languages, so you might not get help soon if you need it. For Mendix, there is the Mendix forum and the marketplace, where you can find many third-party addons, but apart from that there is not much else.
It might be easier to do static code analysis. This depends on the low-code platform. With some, if there is no textual representation of the flow, it will be more difficult to develop tools that analyse it. (this might change with AI but it will take time)

Conclusion

To summarize, visual development is an alternative way to write software. It might feel more natural to many people, can be shared with non-technical people for demonstration purposes, and can help developers to put complex ideas in a more clear mannter.

That being said, traditional code development is not going anywhere and still has advantages of performance and flexibility.

If you are in a position to choose one or the other, consider the pros and cons above and think about factors such as flexibility, performance, ease of development, what skillsets you currently possess.

This way you will find the best approach for you.