From 2c089af949f644892d8be2961e69e3a3de92f4b1 Mon Sep 17 00:00:00 2001 From: Claudio Maggioni Date: Tue, 28 Feb 2023 15:59:47 +0100 Subject: [PATCH] exercise 1 complete, please check --- package.json | 1 + .../model/decisions/0001-ui-is-web-app.madr | 72 +++++++++++++++++++ .../0002-use-docker-for-distribution.madr | 50 +++++++++++++ .../0003-use-rdbms-as-databases.madr | 39 ++++++++++ src/sa/model/decisions/decision-template.madr | 36 ---------- src/sa/model/index.md | 4 +- 6 files changed, 165 insertions(+), 37 deletions(-) create mode 100644 src/sa/model/decisions/0001-ui-is-web-app.madr create mode 100644 src/sa/model/decisions/0002-use-docker-for-distribution.madr create mode 100644 src/sa/model/decisions/0003-use-rdbms-as-databases.madr delete mode 100644 src/sa/model/decisions/decision-template.madr diff --git a/package.json b/package.json index a52940e..66daad0 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ "uslug": "^1.0.4" }, "scripts": { + "start": "open upload/sa/model/index.html && onchange src/** -- yarn build", "build": "node build.js", "clean": "rm -rf upload/*", "watch": "onchange src/** -- yarn build" diff --git a/src/sa/model/decisions/0001-ui-is-web-app.madr b/src/sa/model/decisions/0001-ui-is-web-app.madr new file mode 100644 index 0000000..1485c15 --- /dev/null +++ b/src/sa/model/decisions/0001-ui-is-web-app.madr @@ -0,0 +1,72 @@ +## ADR #0001: The UI is a web app + +1. **What did you decide?** + + The user interface of Smarthut is a single-page web application implemented + using modern frontend web frameworks. + +2. **What was the context for your decision?** + + + The user application of Smarhut should be easily accessible by users and be + compatible with as many devices and platforms as possible. Therefore, the UI + should work on desktop and mobile devices alike. + + + Targeting several platforms poses the challenge of dealing with different + programming language and UI framework constraints. Few paradigms are + universally supported and thus there is a risk of additional complexity and + cost per each custom logic or code a platform may require. + + + This decision affects mainly the frontend side of Smarthut, possibly + constraining UI/UX design freedom. Additionally, due to the way data may be + shown data flow between UI and components evaluating business logic + (e.g. user-defined triggers) and storing state (e.g. user-defined room + configuration) may be affected, thus the connectors between these components + may optimized to fit the chosen way to show the data in the UI. + +3. **What is the problem you are trying to solve?** + + + _Which technology, framework or paradigm should be used to implement the + user interface of Smarthut?_ + + +4. **Which alternative options did you consider?** + + - Producing custom-built apps per each major platform, namely *Android*, *iOS*, + *Desktop* - possibly Windows-MacOS multiplatform, and *Web*) + - Using a market-ready multiplatform technology like Xamarin or + Ionic+Electron, and target the *Web* platform separately + - Focus on the *Web* platform for the first MVP and later target + other platform repackaging the web application (e.g. using PWAs or + Webviews) + +5. **Which one did you choose?** + + - Focus on the *Web* platform for the first MVP and later target + other platform repackaging the web application (e.g. using PWAs or + Webviews) + +6. **What is the main reason for that?** + + Building a web application is cheaper and easier than building for any + other platform due to the ubiquitousness of web products and solutions + nowadays. This is the most suitable choice to have a cheap yet satisfactory + MVP of Smarthut. + + Pros: + + - Cheap development; + - Lots of compatibility with different devices and platforms; + - Ease of repackaging in native applications (through PWAs or Webviews). + + Cons: + + - UX may degradate due to use of non-native components for each platform; + - Performance is inferior than native components; + - The *Web* platform is more limited than other platforms (e.g. for + storage), thus targeting it as a common denominator may impact the ease + of development of features that may be trivial to implement on other + platforms natively. \ No newline at end of file diff --git a/src/sa/model/decisions/0002-use-docker-for-distribution.madr b/src/sa/model/decisions/0002-use-docker-for-distribution.madr new file mode 100644 index 0000000..b72b759 --- /dev/null +++ b/src/sa/model/decisions/0002-use-docker-for-distribution.madr @@ -0,0 +1,50 @@ +## ADR #0002: Use docker for distribution + +1. **What did you decide?** + + The software should be packaged using Docker and docker-compose. + +2. **What was the context for your decision?** + + An easy to use package format should be used to distribute Smarthut to users effectively, allowing + for ease of installation and upgrade. + + The chosen format must be convenient to use both for + the (tinkerer) end user and for the development team + of Smarthut. The format should seamlessly integrate with DevOps pipelines, and should be easily distributable though already established platforms. + + The scope of this decision potentially affects the design of the DevOps pipeline and the final performance of the application. + +3. **What is the problem you are trying to solve?** + + How should the components making up Smarthut be packaged in a single distributable artifact? + +4. **Which alternative options did you consider?** + + - Virtual machine images, possibly generated through + automated tools like Vagrant or Chef; + - Direct binary distribution, employing static linking + for dependencies and an orchestration script; + - Docker images for each component, and a docker-compose + specification for orchestration. + +5. **Which one did you choose?** + + - Docker images for each component, and a docker-compose + specification for orchestration. + +6. **What is the main reason for that?** + + Docker is a de-facto standard for containerization and it pairs nicely + with docker-compose for orchestration. + + Pros: + - Seamless integration with modern DevOps pipeline solutions; + - Established distribution channel (Docker Hub); + - Low performance overhead; + - Existing integrations with low performance and IoT level hardware (e.g. [Balena](https://www.balena.io/)) + + Cons: + - Lack of proper support for Windows and MacOS systems without + building multiple container images, likewise for different + processor architectures (e.g. arm64). \ No newline at end of file diff --git a/src/sa/model/decisions/0003-use-rdbms-as-databases.madr b/src/sa/model/decisions/0003-use-rdbms-as-databases.madr new file mode 100644 index 0000000..fa32b69 --- /dev/null +++ b/src/sa/model/decisions/0003-use-rdbms-as-databases.madr @@ -0,0 +1,39 @@ +## ADR #0003: Use RDBMS as main choice for database technology + +1. **What did you decide?** + + Relational DBMSes shall be used as the main choice to store the state of the Smarthut application in each microservice. + +2. **What was the context for your decision?** + + An effective way to store the state of the various components of Smarthut shall be found. Namely, the DBMS shall store account details, a list of managed devices per user, and all other user-defined configurations like scenes (multi-device configurations) and automation rules (_if event `X` happens, apply scene `Y`_). + + The chosen technology shall store data consistently and allow concurrent access to it, as multiple users may use Smarthut at the same time. Additionally, the chosen DBMS shall be able to maintain data consistency. + + As each microservice will have its own independent data layer (i.e. DBMS instance), this ADR is not an absolute decision. However, this ADR represents the typical (or when-in-doubt) decision to be taken and proposes a general discussion on different DBMS technologies. + +3. **What is the problem you are trying to solve?** + + Which database paradigm shall be preferred to store data in each microservice? + +4. **Which alternative options did you consider?** + + - Relational DBMSes, or RDBMSes; + - Documental database (e.g. MongoDB); + - Persistent key-value storage (e.g. Redis RDB, or custom file serialization) + +5. **Which one did you choose?** + + - Relational DBMSes, or RDBMSes; + +6. **What is the main reason for that?** + + RDBMSes provide ACID properties (atomicity, consistency, isolation, and durability) and schema validation "for free". + + Pros: + - Concurrent access to data; + - Schema definition and validation; + + Cons: + - Distributed DBMS hard to achieve (possible fix: microservice-level + distribution and consensus can be implemented). \ No newline at end of file diff --git a/src/sa/model/decisions/decision-template.madr b/src/sa/model/decisions/decision-template.madr deleted file mode 100644 index fd7f614..0000000 --- a/src/sa/model/decisions/decision-template.madr +++ /dev/null @@ -1,36 +0,0 @@ -## ADR #0 (Template) - -1. What did you decide? - -Give a short title of solved problem and solution - -2. What was the context for your decision? - -What is the goal you are trying to achieve? - -What are the constraints? - -What is the scope of your decision? Does it affect the entire architecture? - -3. What is the problem you are trying to solve? - -You may want to articulate the problem in form of a question. - -4. Which alternative options did you consider? - -List at least 3 options - -5. Which one did you choose? - -Pick one of the options as the outcome of your decision - -6. What is the main reason for that? - -List the positive consequences (pros) of your decision: - -* quality improvement -* satisfaction of external constraint - -If any, list the negative consequences (cons) - -* quality degradation \ No newline at end of file diff --git a/src/sa/model/index.md b/src/sa/model/index.md index df1626b..a61125e 100644 --- a/src/sa/model/index.md +++ b/src/sa/model/index.md @@ -94,7 +94,9 @@ Exceed: >2 ADR } -![Architectural Decision Record Template](./decisions/decision-template.madr) +![Architectural Decision Record 1](./decisions/0001-ui-is-web-app.madr) +![Architectural Decision Record 2](./decisions/0002-use-docker-for-distribution.madr) +![Architectural Decision Record 3](./decisions/0003-use-rdbms-as-databases.madr) # Ex - Quality Attribute Scenario