From 0218d12e896c4327976f9a3968824a6184b98583 Mon Sep 17 00:00:00 2001 From: Marc Gorzala Date: Thu, 23 Nov 2023 14:36:15 +0100 Subject: [PATCH] adrs in separate folder --- .../arc42/src/09_design_decisions.adoc | 117 +--------------- .../documentation/arc42/src/adrs/index.adoc | 125 ++++++++++++++++++ 2 files changed, 126 insertions(+), 116 deletions(-) create mode 100644 src/main/jbake/content/documentation/arc42/src/adrs/index.adoc diff --git a/src/main/jbake/content/documentation/arc42/src/09_design_decisions.adoc b/src/main/jbake/content/documentation/arc42/src/09_design_decisions.adoc index b41f252..4986b7c 100644 --- a/src/main/jbake/content/documentation/arc42/src/09_design_decisions.adoc +++ b/src/main/jbake/content/documentation/arc42/src/09_design_decisions.adoc @@ -1,119 +1,4 @@ [[section-design-decisions]] == Design Decisions -link:https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html[While writing decisions, try to stick to this guide.] - -=== PostgreSQL as our default Database - -[discrete] -==== The problem -There are a lot of different database systems out there for a lot of different use cases. - -As we don't want to discuss what database to use for each new service we write, we want to decide on a default database that will cover most of our use cases. - -Note: We take into account that the chosen database system will probably not cover all our future use cases, which is why we will then decide on a different solution for specific cases if the need arises (which will then be documented as a separate ADR). - -[discrete] -==== Influencing Factors -@Sebastian -maybe I mix this up with Assumptions. Can you have a look at the assumptions, and if parts of them are influencing factors? - -[discrete] -==== Which quality goals are affected? - -This decision affects our Reliability Quality Goal. Issues with our persistent implementation could lead to wrong results, poor performance or even data loss. - -[discrete] -==== Which risks are affected? - -Besides the quality goals that could be missed, choosing the wrong database system could also negatively impact the developer experience. E.g. when we choose a not well-established database system, learning and gaining experience will take up a lot of resources. Some engineers might like this as they also participate in Dancier to learn new technology while others might find it distracting and a waste of their resources to learn a completely new database system. - -In both cases, we will finish our goals later, because of the additional time spent on gaining experience. - -[discrete] -==== Assumptions - -In most cases, we will have to deal with structured data. Also, our current team is well-versed in utilizing SQL databases. - -We are likely in a situation where we need database transactions for implementing patterns like the transactional outbox pattern. - -We also do not expect that most of our databases will need to scale horizontally. If this assumption proves incorrect, we anticipate that moving to another database system will be manageable for us, given our adherence to the clean architecture style (or at the very least the DAO pattern). - -[discrete] -==== Options we considered - -[discrete] -==== MongoDB -MongoDB's main advantage of offering transparent sharding does not pay off for us, as we (see assumptions) do not need horizontal scaling. - -Storing arbitrary JSON documents is also not an advantage (compared to PostgreSQL), as - - 1. We primarily deal with structured data (see assumptions) - 1. PostgreSQL can also store JSON if needed - -We also have relatively limited expertise within the core team in using und operating MongoDB. - -[discrete] -==== PostgreSQL -SQL databases remain the most widely used database systems (links) and PostgreSQL appears to be the most used open-source database system in professional settings (link). - -Every team member can use PostgreSQL since everyone is familiar with the concepts of relational databases. - -Relational databases are highly mature and well-supported by common frameworks like Spring Boot, the framework of our choice. The tooling support is also very mature. PostgreSQL offers the kind of transactions we likely need (see assumptions) and deals well with our mostly structured data. - -Moreover, we have experience in operating PostgreSQL. - -[discrete] -==== Cassandra -This is a similar case as with MongoDB, but in addition to its drawbacks, Cassandra's tooling support is expected to be the least mature among our three options. - -[discrete] -==== Decision - -We have chosen PostgreSQL as our default database. - -This decision can be deducted from our link:https://project.dancier.net/architecture-decision-principles.html[architectural decision principles]: - -[discrete] -===== Skills of team members(AP3)/Principle of least surprise(AP6) - * bad experience with MongoDB and Cassandra on former work projects - * having more knowledge of this database reduces surprises, as potential issues can be anticipated more compared to less familiar database systems - -[discrete] -===== Go Deep not wide (AP5) - -Defaulting to the world's most prominent database architecture (SQL) enables us to become experts in that crucial technology rather than having partial expertise in multiple areas. - -We anticipate achieving better overall results by deeply understanding fewer technologies, rather than having a superficial understanding of a broader range of technologies. - -[discrete] -===== Favor what's proven -Certainly, SQL stands out as the most proven database system in existence ([insert link?]), and PostgreSQL is one of the leading open-source candidates. - -=== Python for all Data science related tasks - -[discrete] -==== The problem -One of our top quality goals is that the recommendations we offer to our dancers should be good. -So we want to use the best tooling and frameworks that help us in implementing a good recommender. -Our main langugage ist Java. So at first, we could implement the recommender in Java. - - -=== Computing Recommendations in its own deployable - -[discrete] -==== The problem -We decided to have Python for all data science related stuff. - -=== Self Contained System for Kikerki - - -=== Batch Mode for computing the recommendations - - - - - - - - +find our Architecural Decision Records link:https://project.dancier.net/documentation/arc42/adrs/index.html[here] \ No newline at end of file diff --git a/src/main/jbake/content/documentation/arc42/src/adrs/index.adoc b/src/main/jbake/content/documentation/arc42/src/adrs/index.adoc new file mode 100644 index 0000000..5066fa2 --- /dev/null +++ b/src/main/jbake/content/documentation/arc42/src/adrs/index.adoc @@ -0,0 +1,125 @@ += Architectural Decision Records +:jbake-type: page +:jbake-status: published +:jbake-date: 2023-11-22 +:jbake-tags: architecture +:jbake-description: All our ADRs +:jbake-author: Marc Gorzala +:idprefix: + + +== ADR01 - + + +link:https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html[While writing decisions, try to stick to this guide.] + +=== PostgreSQL as our default Database + +[discrete] +==== The problem +There are a lot of different database systems out there for a lot of different use cases. + +As we don't want to discuss what database to use for each new service we write, we want to decide on a default database that will cover most of our use cases. + +Note: We take into account that the chosen database system will probably not cover all our future use cases, which is why we will then decide on a different solution for specific cases if the need arises (which will then be documented as a separate ADR). + +[discrete] +==== Influencing Factors +@Sebastian +maybe I mix this up with Assumptions. Can you have a look at the assumptions, and if parts of them are influencing factors? + +[discrete] +==== Which quality goals are affected? + +This decision affects our Reliability Quality Goal. Issues with our persistent implementation could lead to wrong results, poor performance or even data loss. + +[discrete] +==== Which risks are affected? + +Besides the quality goals that could be missed, choosing the wrong database system could also negatively impact the developer experience. E.g. when we choose a not well-established database system, learning and gaining experience will take up a lot of resources. Some engineers might like this as they also participate in Dancier to learn new technology while others might find it distracting and a waste of their resources to learn a completely new database system. + +In both cases, we will finish our goals later, because of the additional time spent on gaining experience. + +[discrete] +==== Assumptions + +In most cases, we will have to deal with structured data. Also, our current team is well-versed in utilizing SQL databases. + +We are likely in a situation where we need database transactions for implementing patterns like the transactional outbox pattern. + +We also do not expect that most of our databases will need to scale horizontally. If this assumption proves incorrect, we anticipate that moving to another database system will be manageable for us, given our adherence to the clean architecture style (or at the very least the DAO pattern). + +[discrete] +==== Options we considered + +[discrete] +==== MongoDB +MongoDB's main advantage of offering transparent sharding does not pay off for us, as we (see assumptions) do not need horizontal scaling. + +Storing arbitrary JSON documents is also not an advantage (compared to PostgreSQL), as + + 1. We primarily deal with structured data (see assumptions) + 1. PostgreSQL can also store JSON if needed + +We also have relatively limited expertise within the core team in using und operating MongoDB. + +[discrete] +==== PostgreSQL +SQL databases remain the most widely used database systems (links) and PostgreSQL appears to be the most used open-source database system in professional settings (link). + +Every team member can use PostgreSQL since everyone is familiar with the concepts of relational databases. + +Relational databases are highly mature and well-supported by common frameworks like Spring Boot, the framework of our choice. The tooling support is also very mature. PostgreSQL offers the kind of transactions we likely need (see assumptions) and deals well with our mostly structured data. + +Moreover, we have experience in operating PostgreSQL. + +[discrete] +==== Cassandra +This is a similar case as with MongoDB, but in addition to its drawbacks, Cassandra's tooling support is expected to be the least mature among our three options. + +[discrete] +==== Decision + +We have chosen PostgreSQL as our default database. + +This decision can be deducted from our link:https://project.dancier.net/architecture-decision-principles.html[architectural decision principles]: + +[discrete] +===== Skills of team members(AP3)/Principle of least surprise(AP6) + * bad experience with MongoDB and Cassandra on former work projects + * having more knowledge of this database reduces surprises, as potential issues can be anticipated more compared to less familiar database systems + +[discrete] +===== Go Deep not wide (AP5) + +Defaulting to the world's most prominent database architecture (SQL) enables us to become experts in that crucial technology rather than having partial expertise in multiple areas. + +We anticipate achieving better overall results by deeply understanding fewer technologies, rather than having a superficial understanding of a broader range of technologies. + +[discrete] +===== Favor what's proven +Certainly, SQL stands out as the most proven database system in existence ([insert link?]), and PostgreSQL is one of the leading open-source candidates. + +=== Python for all Data science related tasks + +[discrete] +==== The problem +One of our top quality goals is that the recommendations we offer to our dancers should be good. +So we want to use the best tooling and frameworks that help us in implementing a good recommender. +Our main langugage ist Java. So at first, we could implement the recommender in Java. + + +=== Computing Recommendations in its own deployable + +[discrete] +==== The problem +We decided to have Python for all data science related stuff. + +=== Self Contained System for Kikerki + + +=== Batch Mode for computing the recommendations + + + +