A new Java Spring Boot service template

The problems with starting a new project

During my various projects I have participated in laying down the groundwork for numerous Spring applications. From setting up the project skeleton, to creating the signup and authorization logic using JWT, forgotten password functionality with different email providers, some kind of a unified error handling and so on.

These are tasks that every new project has to deal with. The team can decide which way they go. Often writing everything from scratch is the selected option. Tech leads and developers often don't trust project templates or generators, they have their own conventions and ways.

Too much magic in the background can lead to problems later on and by the time they realize something is not right it is too expensive to switch the framework. Being stuck with something that you don't like makes work painful and slow and is not a great thing in general. Release cadence and engineer motivation can suffer.

Building things from the ground up every time solves this issue but introduces another one. Companies developing custom software solutions for their customers are in a very intense price race with each other. I had the luck to participate in the creation of many many offers and engineering effort estimations during my years at AutSoft. We always had to calculate with the cost of creating the project skeleton, login, role based access control and so on. We often discussed various options to solve this, but nothing significant happened. We had a few libraries, for error handling for example, but far from a complete starter project.

Project templates to the rescue

Using a boilerplate or template inside the company across projects could have a lot of benefits.

• Similar codebase makes it easier to move engineers between projects, which is often a reality
• Saving 5-10-15 days in an offer on these basic functionalities can really make a difference on the price and thus the competitiveness of the offer. Not necessarily on projects in the 1000+ days range, but below that the overhead of the repeating basics does really count
• Good engineers have a sense for efficiency and making things the right way. Reimplementing the aforementioned functionalities on every project is basically inter-project code duplication, which is a waste of time and resources. Engineers are happier working efficiently
• These kind of templates are also great for PoCs, side projects or solo entrepreneurs working on their product, since in these cases what matters most is the idea and business functions, no one wants to waste time on figuring out how to do secure authorization

There are numerous project templates on the internet aiming to solve these problems. For very fancy and popular languages there are many but for others a little less. For Java there is JHipster and not much else that worth mentioning (tom my knowledge at least).

JHipster is a very nice tool, but maybe a bit too much. It has many many options on what libs you want to use, it even creates an Angular website for your entities with CRUD functionalities which is really nice. It also uses a lot of code generation and may penalize you if you are not doing something in its way.

This is the way

I wanted to create something simpler, with a more opinionated approach, but also more business functionality. The functions I wanted to cover:

• User signup with optional email confirmation
• Social login (Google, Facebook, etc)
• Username + password authentication
• 2FA
• Forgotten password email solution
• User management CRUD API
• Role based access control
• Uniform API error handling and error messages
• Monitoring out of the box (Prometheus + Grafana)
• Docker image build + compose file for local dev and deployment
• All the tools and documentation that developers need in their daily work on the project built with this template (CI integrations, Checkstyle, OpenAPI docs)
• Applying all the conventions and configurations to be a good starter for a cloud native app, either a monolith or microservice
• Examples for usage

Besides these features I also wanted to introduce design philosophies and other tools that I found useful, like the way packages are ordered or the use of Flyway for database migration management.

All the above built using best practices I have learnt during my time as a software architect and tech lead on projects small and big for customers in various industries. The template will definitely be opinionated, but I want to make it easy to modify parts to tailor it to your needs. I also use Spring Boot's built in capabilities as much as I can, I don't want to reinvent the wheel.

I will write a few posts about various aspects of it and design decisions I made during the development.

The template is called This is the way and is coming very soon, stay tuned!