K
K
During the application development process, decisions had to be made as issues emerged. The most interesting design decisions are reflected in this architectural records:
Date Recorded: 01/02/2024
-Scope: frontend, webapp
-Description: -Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application.
-Decision taken: -The frontend team has agreed to use React or a React framework, as all members agree they are not up to the task of maintaining a personalised stylesheet.
-Date Recorded: 01/02/2024
-Scope: frontend, webapp
-Description: -The frontend team has been discussing whether to use React or a React framework like Next.js as it is the currently recommended option.
-Decision taken: -The frontend team has agreed to use a pure React-based approach due to most members not having any kind of prior experience with React and those that do have it are do not feel confident enough in their skills.
-Date Recorded: 01/02/2024
-Scope: backend, API
-Description: -The backend team wants to deprecate the given Node.js microservices system in favour of a monolithic Springboot-based approach. This is mainly due to only one member having prior experience in Node.js development. No members support keeping the current approach, and when asked if SpringBoot would allow a possible microservices constraint, a member of the backend team has stated that a proper-developed SpringBoot application should be easy to divide between different microservices.
-Decision taken: -The backend team has agreed to use SpringBoot and JPA for the backend.
-Date Recorded: 01/02/2024
-Scope: database
-Description: -A member of the backend has proposed the replacement of MongoDB as DBMS, with PostgreSQL replacing it. A member of the frontend team has supported it, remarking modern DBMS have built-in JSON support if needed. Other members of the backend team have stated their agreement, as many of them do not have prior experience with MongoDB and prefer relational databases.
-Decision taken: -The team has agreed to drop MongoDB and to use PostgreSQL.
-Date Recorded: 09/02/2024
-Scope: frontend, webapp
-Description: -To enhance the efficiency and effectiveness of our development process, we’ve taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16.
-Decision taken: -The team has agreed to use Chakra UI as the main library for the frontend.
-Date Recorded: 23/02/2024
-Scope: security
-Description: -To improve security we have decided to make HTTP/2 and HTTPS one of the main requirements in our project as can be seen in issue #51.
-Decision taken: -The team has agreed to use HTTP/2 and HTTPS.
-Date Recorded: 03/03/2024
-Scope: backend, question generator
-Description: -The question generator must be a part of our application, but different to the webapp or the API, it doesnt need to be running on a loop. It just needs to be run once everytime we want to load or update questions. Implementing it in the API module would result on more coupling but not duplicating code for the model. On the other hand, implementing it in a new module would make the application cleaner and easier to change.
-Decision taken: -The team has decided to implement the question generator as a separate module of our application.
-Date Recorded: 10/03/2024
-Scope: backend, question generator, database
-Description: -The backend team has been discussing whether to use JPA or JDBC to connect to the database with the question generator. When researching JPA it was found that although it is easier to use since the models already exist in our API, the models cannot be used from a different package, which makes us duplicate code as we do not have time to research another way of implementing it. On the other hand, JDBC would be more complex to use and does not have the same level of flexibility as JPA.
-Decision taken: -The team has agreed to use JPA to connect to the database with the question generator. Although this will generate duplication of code in the models, it should be manageable due to the small size of the project. This will be recorded as technical debt and new approach should be looked into if the project grows in size.
-Date Recorded: 19/03/2024
-Scope: backend, game logic
-Description: -The game logic must be implemented in the backend, since implementing it in the frontend would make it very dependent on performance and prone to allowing cheating and exploits. The questions will be served to the frontend each round but then validated in the backend, to prevent cheating. Points will also be automatically calculated in the backend.
-| Decision | +Explanation | +
|---|---|
React |
+Offers a powerful combination of performance, flexibility, and developer experience, making it a popular choice for building modern web applications. One of the members of the group has already worked with it in the past. It allows us to build a good user interface for the application. |
+
SpringBoot |
+This choice is based on the extensive experience accumulated by our team in developing with Java, as well as the familiarity and comfort offered by the tools and practices associated with the Spring Boot ecosystem. |
+
PostgreSQL |
+We have chosen to use the PostgreSQL database instead of MongoDB due to the relational nature of PostgreSQL, which offers a robust and coherent structure for storing and relating data. We made this decision to ensure data integrity, perform complex queries, and maintain consistency in our storage operations. |
+
React Libraries |
+To enhance the efficiency and effectiveness of our development process, we’ve taken proactive steps to incorporate specific libraries into our project. These carefully chosen libraries, meticulously outlined in detail within issue #16. |
+
HTTPS |
+To improve security we have decided to make HTTPS as one main requirements in out project as can be seen in issue #51. |
+
Architecture of the Question Generator |
+It has been decided to implement the QG in an independent module so it is only run once and it is not generating questions at real time, this way, we are not dependent on wikidata for having our application available. |
+
Template method pattern |
+We chose to apply our software design knowledge and generate the questions following a template method in Java. This allows us to create new questions easily and without duplicating too much code. |
+
Use of JPA in the Question Generator |
+We used JPA in favor of JDBC as when tables are related in a DB, JPA makes it easier to write into the DB. |
+
Decision taken: -The team has agreed to implement the game logic in the backend to make it more robust and prevent cheating.
+If needed, more details are given in the wiki.
It is probably the first time involvement in developing a project from scratch, including decisions on architecture, design, and implementation, introduces various challenges. Misunderstandings regarding tasks and version control management errors can result in individuals inadvertently disrupting the work of others. Additionally, the necessity to make numerous decisions and reach agreements increases the likelihood of errors, potentially consuming significant time and effort.
To ensure effective collaboration and organization, adhere to the teachers' instructions concerning GitHub, including utilizing features such as issues and pull requests, and maintain a disciplined approach to your work. Furthermore, leverage the collective knowledge and suggestions of every team member, integrating them with your existing expertise.
Hardcoded url in prometheus.yml
We do not have the expertise in prometheus to know how to properly set up the URL, so we decided to harcode it.
Investigate the way to use a variable in the file and use it.
Hardcoded ip in graphana dashboard.yml
As in the previous case, we do not have the expertise in graphana to know how to properly set up the IP, so we decided to harcode it.
Investigate the way to use a variable in the file and use it.
Non optimal code (loadAnswers)
When designing the application we did not take into account that two users may have the same question given to them at the same time. To solve a problem that would arise with that, we decided to just load the distractors of a question once and use the same distractors for all following games, this means that a question always has the same distractors which can get boring.
Rewrite the code (which means altering the workflow) so the distractors are load per game and user, so everytime a questions is asked, the distractors are different.
Use of "supress warnings"
We use Lombok to annotate our classes and make the code lighter, this means that getters and setters are generated by the annotations and not explicitly written in our code, due to this, SonarCloud thinks that our private attributes are not used (the getters and setters are public and used by outside classes, but SonarCloud does not detect that).
Sadly, at this moment we do not think this can be avoided, so the mitigation is just to wait for a SonarCloud update that does detect this.
Questions tied to ID
Questions are tied to the game entities by means of relational tables via id, which makes it difficult to update if they change.
Creating a unique identifier for each question that can stay throughout versions, so we do not need the BD autogenerated ID to access them.
JWT handling could be improved
Handling the session has been difficult and we came up with a solution that works, but can be improved.
We should investigate how to improve session handling, as an example using React context
Usage of React
React has proven to be a pain to work with, so we could change it for better options in case we shall continue the developing of the application.
Changing to Vue.js should be considered.
Queries are hardcoded
To write the questions faster and prevent losing time with possible bugs we hardcoded the queries to Wikidata, which makes the code less readable and maintainable.
The queries can be written in an external file and then read in the code, possibly using a properties file.
QG code can be refactored for lighter classes
As with all the projects in Software developing, as you code you find yourself repeating lines, this has happened in the Question templates, which makes it a bit tedious to change those files.
More abstract classes should be included between the QuestionTemplate.java class and each implementation of it.
Use of relational DB for questions
We started using a relational DB as we were more comfortable with it, but it caused its own troubles, as repeating many lines in the DB.
Using a NoSQL DB as Neo4j for storing the questions could be better as it would be lighter and we would keep the relations that exist in Wikidata between questions.
e2e ran in local
We had many troubles trying to set up the e2e in the actions, as they include setting up the db and filling it before this tests are started.
We should investigate about this and learn how to set up the tests.
The name of our project
Question Generator
Question Generator (QG)
A module of the application responsible for querying Wikidata, creating the questions and storing them in our DB