General
Safi Bank is build as a scalable microservice solution. This page intention is to guide development of all backend services by microservice patterns. Rules here are considered as a guidelines, and are not mandatory however, there should be strong reason to deviate from it in general. As an example of microservice can be used the module TransactionHistoryManager.
Technologies used
JVM - microservices are built on top of Java platform, specifically we use Open JDK 17. Specifically, for docker image creation we use JIB, and thus using Eclipse Temurin as base image for the produced images. JDK 17 is used because it is LTS, and we will stick to the latest following minor releases.
Gradle - gradle is used as JVM build tool. We are using wrapper style, meaning, that execution binary is bundled together with source code, and therefore, apart from JDK, there is no need to download nor configure any tool to be able to build artifacts or to run local tests.
Kotlin - is the language of choice, as it offers wider set of features as standard Java and there is broad and supportive community. As for syntax we follow Kotlin coding conventions.
Micronaut - is the core implementation framework inspired by Spring framework.
In future, we might consider using Graal VM to lower image size/speedup startup, however due to technical limitations & partial java incompatibility, this is considered a potential future improvement.
New microservice creation
As we are using Micronaut, recommended way to start with new micronaut project is to use Micronaut Launch. However for new microservice in SaFi project we created template, which contains skeleton of microservice as we recommend.
When creating new microservice, “validate“ github workflow should be created as well - it will run gradle build on each pull request(and subsequent pushes to given branch where PR is open).
Create new yml file based on template validate workflow, only update two entries in “paths” as well as microservice_name.
Documentation
Microservice specific documentation is stored within microservice folder directly in repository. Not in Confluence or anywhere else. The reason for this is to have documentation versioned and aligned together with source code. For writing documentation we use markup language called Markdown. Documentation is structured in following way:
In root folder of the microservice, where are located gradle and gradle config files, is file named 'readme.md'. This file contains:
Brief description of microservice from business perspective. What this service does.
Installation - meaning mainly all the environment entries needed to run the service. This is especially needed for devops team, so they know, which parameters are needed for running container in Kubernetes. This list can change over time, so be careful to update documentation together with list of parameters needed, ideally in the same commit.
All information, which can be handy for developers, which are specific for microservice. This can be list of URLs, or simple tutorial how to run integration tests locally (if possible).
Details regarding architecture, or more technical concepts are stored as structured documents and referenced using hyperlinks. All of this content is stored in ‘docs’ folder which sits next to ‘src’ folder.
In ‘doc’ folder is maintained microservice documentation containing more details about microservice, if needed, including architecture and some peculiar pars of source code. This folder is not mandatory, however, if any documentation apart from ‘readme.md’ exist, it should reside here.