From 0c158f8ab00102935f026a02ea94893d443127a9 Mon Sep 17 00:00:00 2001 From: Lorenz Herbst Date: Mon, 17 Apr 2023 10:58:28 +0200 Subject: [PATCH] introduce first ADRs --- docs/decisions.md | 18 ------------- .../01-choose-frontend-backend-frameworks.md | 22 ++++++++++++++++ docs/decisions/02-use-maven-as-build-tool.md | 21 ++++++++++++++++ .../03-generate-api-models-with-OpenAPi.md | 20 +++++++++++++++ ...4-liquibase-as-database-migrations-tool.md | 22 ++++++++++++++++ .../05-kubernetes-for-frontend-and-backend.md | 19 ++++++++++++++ docs/decisions/adr-template.md | 25 +++++++++++++++++++ 7 files changed, 129 insertions(+), 18 deletions(-) delete mode 100644 docs/decisions.md create mode 100644 docs/decisions/01-choose-frontend-backend-frameworks.md create mode 100644 docs/decisions/02-use-maven-as-build-tool.md create mode 100644 docs/decisions/03-generate-api-models-with-OpenAPi.md create mode 100644 docs/decisions/04-liquibase-as-database-migrations-tool.md create mode 100644 docs/decisions/05-kubernetes-for-frontend-and-backend.md create mode 100644 docs/decisions/adr-template.md diff --git a/docs/decisions.md b/docs/decisions.md deleted file mode 100644 index f6241cc..0000000 --- a/docs/decisions.md +++ /dev/null @@ -1,18 +0,0 @@ -# Project specific Decisions - -## Maven based Reactor Setup - -Be it a VueJS-application or a Spring Boot-Application, everything can be build separately or together depending on the directory you execute your maven commands. -This enables us to use a single build-management system in order to get everything up and running. - -## API first with OpenAPI - -OpenAPI v3 is used as contract between our frontend and backend. -We are leveraging OpenAPI Generator in order to generate client-, server- and model-classes. -This enables us to have a single definition for our Request- and Response-models. -- [kotlin-spring](https://openapi-generator.tech/docs/generators/kotlin-spring) - -## Database Migrations using Liquibase - -Liquibase is used to store our database schemas in a VCS and executes those against our Database on application starts up. -It helps us (re)deploying our Database reliably, while simultaneously keeping its state away from our application runtime/code. \ No newline at end of file diff --git a/docs/decisions/01-choose-frontend-backend-frameworks.md b/docs/decisions/01-choose-frontend-backend-frameworks.md new file mode 100644 index 0000000..9d75356 --- /dev/null +++ b/docs/decisions/01-choose-frontend-backend-frameworks.md @@ -0,0 +1,22 @@ +# Language / Technology of Frontend and Backend + +## Status + +accepted + +## Context + +Languages and Frameworks for both frontend and backend need to be selected. + +## Decision + +Frontend: + - VueJs: Equaly demanded technologie compared to React. Build knowledge abotu VueJS across team members. +Backend: + - SpringBoot / Kotlin: Both highly demanded technologies in the market. We chose this framework to build up knowledge across + team members + +## Consequences + +We are utilizing technologies that are currently in high demand in the market. It is important for us to familiarize +ourselves with these technologies and take advantage of the opportunity to develop valuable knowledge. \ No newline at end of file diff --git a/docs/decisions/02-use-maven-as-build-tool.md b/docs/decisions/02-use-maven-as-build-tool.md new file mode 100644 index 0000000..f24eb46 --- /dev/null +++ b/docs/decisions/02-use-maven-as-build-tool.md @@ -0,0 +1,21 @@ +# Choose Build Tool + +## Status + +accepted + +## Context + +We are building a new project that involves developing applications using Vue.js and Spring Boot technologies. +A build management system to efficiently manage the build process for the project has to be identified. + +## Decision + +Regardless of whether it's a Vue.js frontend application or a Spring Boot backend application, +both can be built independently or combined, depending on the directory where Maven commands are executed. +This enables us to utilize a single build management system and simplifies the build process. + +## Consequences + +The building process for frontend and backend can be easily managed. +As Maven may not be familiar to all team members, some may need to learn and develop competence in using it. \ No newline at end of file diff --git a/docs/decisions/03-generate-api-models-with-OpenAPi.md b/docs/decisions/03-generate-api-models-with-OpenAPi.md new file mode 100644 index 0000000..e5ef365 --- /dev/null +++ b/docs/decisions/03-generate-api-models-with-OpenAPi.md @@ -0,0 +1,20 @@ +# choose generator tool for client-, server- and model-classes + +## Status + +accepted + +## Context + +A tool for generating client-, server- and model-classes needs to be chosen. + +## Decision + +OpenAPI v3 is used as contract between our frontend and backend. +We are leveraging OpenAPI Generator in order to generate client-, server- and model-classes. +This enables us to have a single definition for our Request- and Response-models. + +## Consequences + +Reduces development time and effort as it generates code based on the OpenApi specifications. +Knowledge across the team members needs to be built. diff --git a/docs/decisions/04-liquibase-as-database-migrations-tool.md b/docs/decisions/04-liquibase-as-database-migrations-tool.md new file mode 100644 index 0000000..81c8cce --- /dev/null +++ b/docs/decisions/04-liquibase-as-database-migrations-tool.md @@ -0,0 +1,22 @@ +# Liquibase as database migrations tool + +## Status + +accepted + +## Context + +Find a system that simplifies the management and deployment of database changes. + +## Decision + +Liquibase is used to store our database schemas in a VCS and executes those against our Database on application start up. +It helps us (re)deploying our Database reliably, while simultaneously keeping its state away from our application runtime/code. +It helps us to manage changes database schema and data in a version-controlled manner. + +## Consequences + +We need to learn syntax and conventions of liquibase. +Changesets need to be managed properly, otherwise it is possible to end up with different schema versions on different +working states / branches. +Also version control conflicts can happen, if multiple developers make changes to the same changesets simultaneously. \ No newline at end of file diff --git a/docs/decisions/05-kubernetes-for-frontend-and-backend.md b/docs/decisions/05-kubernetes-for-frontend-and-backend.md new file mode 100644 index 0000000..1e72a09 --- /dev/null +++ b/docs/decisions/05-kubernetes-for-frontend-and-backend.md @@ -0,0 +1,19 @@ +# Kubernetes environment for frontend and backend + +## Status + +accepted + +## Context + +Kubernetes is in high demand in the market. Strategic orientation towards adopting this technology. + +## Decision + +Run the project on Kubernetes, which not only meets current technology requirements, but also provides +the team with the opportunity to build and expand knowledge on Kubernetes. + +## Consequences + +The project team must extensively familiarize themselves with Kubernetes. +As the project is open-source, we also want it to be deployable as Docker container. \ No newline at end of file diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md new file mode 100644 index 0000000..908caa8 --- /dev/null +++ b/docs/decisions/adr-template.md @@ -0,0 +1,25 @@ +# Decision record template by Michael Nygard + +This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). +You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files. + +In each ADR file, write these sections: + +# Title + +## Status + +What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +## Decision + +What is the change that we're proposing and/or doing? + +## Consequences + +What becomes easier or more difficult to do because of this change? +The Team needs to learn how to utilize OpenApi. \ No newline at end of file