T
T
T
The WIQ web application is developed by HappySw for RTVE to create an experimental version of the Saber y Ganar quiz show. +The primary goal of WIQ is to provide users with an engaging platform where they can participate in quiz games, +answer questions generated from Wikidata, and win prizes.
+This document outlines the essential requirements guiding the software architects and development team in creating WIQ.
+Quality Goal |
+Description |
+
Reliability |
+Ensure consistent and accurate question generation and user data management. |
+
Performance |
+Optimize system response times and capacity to handle multiple user interactions simultaneously. |
+
Security |
+Implement robust security measures to protect user data and prevent unauthorized access. |
+
<Role-1>
<Contact-1>
<Expectation-1>
Users
N/A
Intuitive and enjoyable quiz experience
<Role-2>
<Contact-2>
<Expectation-2>
RTVE
Project Manager
Reliable and engaging platform for users
HappySw Team
Development Team
Clear documentation and reliable system performance
When designing the WIQ application, there are several constraints that must be taken into consideration, as they will have a significant impact on the overall design of the application and the architectural decisions. These constraints must be considered in order to ensure that the final product meets the needs and expectations of the users and stakeholders. The following table summarizes these constraints and provides a brief explanation for each one divided into technical, organizational and political constraints.
+Constraint |
+Explanation |
+
WikiData |
+Our application must generate questions automatically getting data from WikiData |
+
Docker |
+We are using docker for the deployment.It’s a platform that allows you to package Our application and its dependencies into a standardized unit called a container. |
+
Azure |
+Azure is a cloud computing platform where we are going to host our WIQ application |
+
Version control and monitoring (GitHub) |
+For the WIQ application, GitHub is a useful tool for version control and collaboration among the team members working on the project. It allows easier coordination and organization of the development process, as well as keeping track of changes and contributions made by each team member. |
+
User Experience |
+The design of the application must make its use friendly and easy |
+
Test coverage |
+Code must meet a good test quality and coverage to ensure the expected outcome. |
+
Constraint |
+Explanation |
+
Team |
+The project will be done in a team composed of 7 students, so work must be assigned accordingly. |
+
Git-based development |
+The project will be built around the Git workflow, so all tools used must be able to closely interact with this system. |
+
Meetings |
+The project’s development process must be reflected in the minutes of each meeting that happens. |
+
Delivery deadlines |
+There are 4 deliverables every 3 weeks that should be followed accordingly before the deployment of the application |
+
Constraint |
+Explanation |
+
Documentation |
+We are going to use AsciiDoc and follow the Arc42 template. |
+
Language |
+The documentation and application will be developed in English. |
+
<Diagram or Table>
+
<optionally: Explanation of external domain interfaces>
| Partner | +Input | +Output | +
|---|---|---|
User |
+The user interacts with the WIQ web application using the front-end of the application. |
+The display of a page of the application with the questions and statistics. |
+
Database |
+Stores relevant information of the application (users, number of games, questions passed/failed, times…). |
+Retrieves the information that the application requires. |
+
Question generation |
+Questions generated from Wikidata. |
+These generated questions are sent to the application. |
+
Wikidata API |
+Receives a query linked to the question to be asked. |
+Returns the necessary information to formulate the question. |
+
<Diagram or Table>
Component |
+Technologies Used |
+
Front-end |
+HTML, CSS, JavaScript (Svelte/React) |
+
Back-end |
+.NET/node.js, API de Wikidata |
+
Database |
+MongoDB |
+
Arquitechture |
+Microservices |
+
Deployment and Maintenance |
+Docker |
+
<optionally: Explanation of technical interfaces>
<Mapping Input/Output to Channels>
Component |
+Functionality |
+
Front-end |
+User interaction and results display. |
+
Back-end |
+Logical processing, communication with external API and database. |
+
Database |
+Data storage. |
+
External API |
+Data query from Wikidata. |
+
In this flow: +- The user interacts with the user interface (front-end) through clicks and responses. +- The back-end processes the requests, consults the Wikidata API, and updates the screen. +- The channels are the HTTP connections between the components. +- The mapping evaluates the user’s responses in real time to provide an appropriate response.
+This section will cover all the technological, architectural, design and organizational decisions made along the project for its appropiate development
+React: JavaScript library for web and native user interfaces. It allows developers to create interactive web applications by breaking down the UI into reusable components. React uses a declarative approach to efficiently update and render components, resulting in faster and more maintainable code. It’s widely adopted in the industry due to its simplicity, performance, and robustness.
+Svelte: modern JavaScript framework that compiles code at build time for efficient updates to the DOM. It emphasizes smaller bundle sizes and better performance, offering a simpler approach to building dynamic web applications compared to traditional frameworks like React or Vue.
+Node.js: JavaScript runtime that enables running JavaScript code outside of web browsers. It’s renowned for its event-driven architecture and extensive collection of packages, making it ideal for building scalable server-side applications. ++ Express.js: Express.js, often simply called Express, is a minimalist web application framework for Node.js. It simplifies the process of building web applications by providing a robust set of features, including middleware support, routing, and templating engines. Express is known for its flexibility, simplicity, and performance, making it a popular choice for developing web applications and APIs in Node.js.
+.NET: versatile developer platform for creating web, mobile, desktop, and cloud applications. It supports multiple programming languages and provides a rich set of libraries and tools for building software solutions. With built-in support for creating APIs and consuming web services, .NET makes it simple to develop and integrate with backend systems and services.
+Wikidata: Wikidata provides a REST API for retrieving information related to any topic. It helps us to dynamically generate questions for our game using it from any programming language.
+MongoDB: popular NoSQL database known for its flexibility and scalability. It stores data in flexible JSON-like documents and is widely used in modern web development for its simplicity and ability to handle large volumes of data.
+Cucumber: Testing tool that supports Behavior Driven Development (BDD) and allows us also to comply testability quality attribute.
+Arc42: framework (template) used for documenting and communicating software architectures. It provides a template for describing the architecture of a software system, covering aspects such as stakeholders, requirements, architecture decisions, components, interfaces, and quality attributes. arc42 helps teams create consistent and comprehensible architecture documentation, enabling better communication, understanding, and maintenance of software systems throughout their lifecycle.
+npm: default package manager for Node.js, providing a command-line interface to install, manage, and publish JavaScript packages. With over a million packages available in its registry, npm simplifies adding functionality to Node.js projects by handling dependencies and providing tools for versioning and publishing packages.
+Docker: platform that will be used for deploying our services inside containers. Containers are lightweight, portable, and self-sufficient units that contain everything needed to run an application, including the code, runtime, system tools, libraries, and settings. Docker enables developers to package their applications along with all dependencies into containers, ensuring consistency across different environments, such as development, testing, and production.
+Microservices: is an architectural style that structures an application as a collection of loosely coupled services. Each service is independently deployable, scalable, and can be developed using different programming languages, frameworks, or databases. +In a microservices architecture, each service typically represents a specific business function or capability and communicates with other services through well-defined APIs. This enables teams to work independently on different parts of the application, allowing us to divide the work into different teams avoiding bottlenecks during production.
+APIs: using microservices architecture enforces us to isolate each of the microservices and create well-defined interfaces for accesing those microservices from common gateway, reducing dependencies between services and allowing them to evolve independently. Well-defined interfaces imply not only services independance, but also team members independecance since nobody will need to wait for others for starting working themselves.
+--------------------(This could be another option if we eventually decide not to use microservices architecture)--------------------
+MVC (Model-View-Controller): is a software architectural pattern which divides an application into three interconnected components: the Model, which represents the data and business logic; the View, responsible for the presentation layer and user interface; and the Controller, acting as an intermediary between the Model and View. MVC promotes separation of concerns, making it easier to manage and maintain complex web applications by enabling developers to work on different components independently. This pattern enhances code reuse, improves testability, and facilitates scalability, contributing to the development of robust and maintainable web applications across various frameworks and programming languages.
+For developing this project we are using Github as the control version systems. +The master branch contains the final version of the product, so that every accepted pull request to master branch will be considered as a new release. +The production branch contains the work in production right now, from where everybody should create their own branch for their specific code development.
+Documentation: it must be always updated for making our work valuable and consistent.
+Weekly meetings: Weekly discussions about what has been done and what needs to be done will be key for our team success.
+Github: this control version systems not only allows us to share and collabortively write code, but also provides other resources such as issues and project management (kanban board) tools for organizing the work to be done. Also, wiki section allows us to save all of our minutes from each scheduled meeting.
+Whatsapp: will allow us to be in constant communication for helping each other out whenever needed.
+Discord: useful for making unofficial meetings and making decisions whenever is impossible for all of us to be present in an specific place.
+<Overview Diagram>
+
+<text explanation>
+This is a basic introduction to the app, highlighting the external services it uses and how they work together.
<Description of contained building block (black boxes)>
-<Description of important interfaces>
-| Name | +Responsibility | +
|---|---|
WIQ |
+It’s the main application, currently represented as a whitebox. The following sections will break it down in detail. |
+
WikidataAPI |
+External API used as the knowledge hub. |
+
+The reasoning behind this separation is to achieve a modular architecture with clear separation of concerns. +It also allows to expose the user management and the question generation as APIs.
+| Name | +Responsibility | +
|---|---|
Frontend |
+Represents the user interface and manages the quiz logic of the application. |
+
User Management |
+Handles everything related to user accounts. |
+
Question Generator |
+Generates questions from Wikidata data and sends them to the frontend. |
+
| Name | +Description | +
|---|---|
Frontend <→ User Management |
+This interface defines how the frontend communicates with the User Management Service to log in, retrieve user data, or perform actions requiring authorization. |
+
Question Generator <→ Frontend |
+This interface defines how the Question Generator Service delivers processed questions to the frontend for display. |
+
Question Generator <→ Wikidata API |
+This interface represents the service fetching data from the Wikidata API. |
+
Here you describe <black box 1> +according the the following black box template:
+Purpose/Responsibility
+Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.
+(Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ….
+(Optional) directory/file location
+(Optional) Fulfilled requirements (if you need traceability to requirements).
+(Optional) Open issues/problems/risks
+<Purpose/Responsibility>
@@ -1078,32 +1649,33 @@<(optional) Open Issues/Problems/Risks>
==== <Name black box 2>
<black box template>
==== <Name black box n>
<black box template>
==== <Name interface 1>
…
==== <Name interface m>
+<white box template>
+
+<white box template>
+…describes the internal structure of the Question Generation Service.
+…
<white box template>
<white box template>
<white box template>
Sequence diagram for showing the process of a user logging in:
+
+Sequence diagram for showing the process of a user creating an account:
+
+The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:
+Our project is configurated using GitHub actions in such a way that every release that is made will trigger some unitary and end to end test, and an attempt to deploy the application over a server. +This will allow our team to achieve continuous deployment and delivery.
Using your Azure account:
+Create an Ubuntu-20.04 virtual machine from Azure www.portal.azure.com
important use cases or features: how do building blocks execute them?
+Select an available location (usually Switzerland North, Zone 1, is available)
interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?
+Select the virtual machine "Standard B1s (1 vcpu, 1GiB of memory)"
operation and administration: launch, start-up, stop
+Set the username to azureuser
error and exception scenarios
+Allow SSH on port 22
Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.
-You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. -You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).
-There are many notations for describing scenarios, e.g.
-Configure GitHub repository secrets with the server’s information:
numbered list of steps (in natural language)
+Download the private key (.pem file) and paste all of its textual content over DEPLOY_KEY. Save the file for later configurations over SSH at the virtual machine.
activity diagrams or flow charts
+Check the public IP at Azure and paste it over DEPLOY_HOST.
sequence diagrams
+DEPLOY_USER does not need to be changed
BPMN or EPCs (event process chains)
+state machines
+Once the virtual machine is created and the repository is configured, go to Network Settings and add extra rules:
+Open port number 3000 for user services
…
+Open port number 8000 for accessing the web application
+More services will be available in the future, so discussions will be made for additional ports supporting our services.
See Runtime View in the arc42 documentation.
+ + +Configure the virtual machine connecting through SSH for using Docker:
+Use some tool for connecting to the server using SSH (PuTTY, MobaXterm…)
+Use the public IP address and the local .pem file for making the connection.
+Run the following commands for preparing the virtual machine:
+sudo apt update+
sudo apt install apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -+
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"+
sudo apt update+
sudo apt install docker-ce+
sudo usermod -aG docker ${USER}
+sudo curl -L "https://github.com/docker/compose/releases/download/1.28.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose+
sudo chmod +x /usr/local/bin/docker-compose+
Make a release in GitHub:
<insert runtime diagram or textual description of the scenario>
+On the right-hand side of the main Code section of our repository, there is a section called Releases. It will be needed to add a new version following the version naming convention.
+Once the release is made, some GitHub actions will be triggered, and the containers will be tested and running once everything finishes.
<insert description of the notable aspects of the interactions between the -building block instances depicted in this diagram.>
+If some test fails during the process, deployment will be automatically aborted.
It is possible to use a sequence diagram:
+General view of system’s infrastructure
+
The Ubuntu server allows us to have a isolated machine with the minimal required configuration and installations for running our services. +Having our server on Azure, allows us to minimize the costs of having that machine running, as well as to avoid taking care of some responsabilities such as security, availability or maintainance.
Instead of having a virtual machine for running the whole application by itself, the application is splitted into different services that can be completely isolated. +Docker allows us to create containers with the minimum amount of resources needed for running that specific service, such that resources are not wasted and services that could be more used do not collapse others. Each container contains the specific docker image for running the specific service. +Each implemented service will be isolated at deploy time, so there is no need of making the services at the same programming language or following the same architectural patterns, and responses will be responded through different independent endpoints.
The virtual machine will contain as many containers as services in the application.
For now, the project contains: + Web application service running on port 3000 +* Gateway (middleware) service running on port 8000 +* Users and authentication services running on ports 8001 and 8002 respectively + Mongo DB server running on port 27017 + Prometheus running on port 9090 for monitoring + Grafana running on port 9091 for analytics and monitoring
+GitHub actions will provide us with continuous automatic delivery and integration, automating the deployment phase at each release.
<diagram + explanation>
<diagram + explanation>
<diagram + explanation>
Along the process of developing the application, decisions had to be taken as problems arise. +These are the initial decicision that we have made but they change during the course of the project +The following table contains some of the design decisions that were imposed to us due to the architectural constraints:
+Code |
+Decision |
+Advantages |
+Disadvantages |
+
ID1 |
+React.js or Svelte |
+Quite easy to learn in comparison to other front-end libraries. Increasingly popular in the web. |
+Not all of us know about its usage |
+
ID2 |
+MongoDB |
+It does not need to be started manually. Free and easy to understand |
+We are quite new with MongoDB. |
+
ID3 |
+Docker |
+Fast deployment, ease of moving/maintaining your applications. Easy as we already have DockerFiles example |
+We do not have much experience using Docker |
+
ID4 |
+PlantUML |
+Allows drawing diagrams very easily, with a simple syntax. |
+Does not allow as much control over the exact layout of the elements in the diagram as other tools. |
+
| Code | +Context | +Record | +
|---|---|---|
ADR1 |
+TBD |
+TBD |
+
ADR2 |
+TBD |
+TBD |
+
+Usage scenarios
+| Quality goal | +Motivation | +Usage scenario | +Priority | +
|---|---|---|---|
Reliability |
+The application must provide users with constistent performance and predictable results. |
+When users access the web it must behave the same every time giving the almost equal results and response times. |
+Very high |
+
Performance |
+The application must have a reasonable response time. Slow applications are not positively popular in society. |
+The application must be able to give a fast response time to the users so the game is dynamic and entertaining. |
+Very high |
+
Security |
+Our web must be secure not only to protect data but to provide a realiable solution to our users. If we can’t assure our clients the web is secure, no one will use it. |
+Data will be only accessible by its owner. If a user tries to access other people’s information, the system will deny the operation, as data will be stored in a secure system. |
+Very high |
+
Portability |
+To reach the maximum number of users the application must work in the maximum number of infrastructures. |
+When users access the web from different browsers and devices, it must work and provide all the possible functionalities. |
+Very high |
+
Usability |
+To make the website stand out from the competition, it must be easy to use, attract attention and be aestethic. |
+When the user wants to do something in the application, he/she should be able to do it without difficulty, guided by the interface elements. |
+Very high |
+
Testability |
+All features of the application must be testable in order to verify that the web built was the one asked for. |
+The unit tests passed by the developers must generate an observable output. |
+High |
+
Availability |
+The application must be available 24 hours a day all weeks. |
+The user must be able to play at any time because it will be its free time. |
+High |
+
Change scenarios
+| Quality goal | +Motivation | +Change scenario | +Priority | +
|---|---|---|---|
Maintainability |
+An application should be maintainable to remain usable over the years and to be able to improve functionalities and to fix misfunctionalities. |
+When developers must introduce a new feature to the web, they should be able to do it without changing the software architecture. |
+High |
+
Maintainability |
+An application should be maintainable to remain usable over the years and to be able to improve functionalities and to fix misfunctionalities. |
+When fixing errors and bugs on the system, developers should be able to do it without major consequences on the system. |
+High |
+
This section contains a list of identified risks that the project will face during its lifetime. In addition to it, each particular risk comes with a brief +self-explanatory description, the probability of its occurrence, its impact on the project and a solution on how to minimize it or mitigate it.
+| Risk | +Description | +Probability | +Impact | +Solution | +
|---|---|---|---|---|
Complications with the project characteristics |
+Almost everyone on the team has never done a project of such a size, and there may be some trouble. |
+Medium |
+High |
+Each member will try to maximize its knowledge on some aspect of the project in the first weeks, in order to be able to be something similar to a leader in each one of the posible key aspects of the project. |
+
Problems with Svelte |
+As a team we decided to try a new language for the front-end. |
+High |
+High |
+The team will practice with the language to be able to do a good job when implementing the front-end. |
+
Problems with wikidata |
+The team only used wikidata once before and not even everyone of us. |
+High |
+Very high |
+We must read some documentation and try out some basic features to familiarize with wikidata. |
+
Teamwork issues |
+The members of the team have never worked together. This may cause problems such as lack of communication or trust in each other’s work. |
+Medium |
+Medium |
+We will try to keep in touch a few times a week, to see each ones progress on our tasks and we will try to build some confidence with each other throughout the development of the project as most of us met on this subject. |
+
Differences with technologies |
+There are some members that don’t know as much in some aspects of the development |
+Medium |
+Low |
+The members that know more on each of the aspects will help the others understand the things they could find difficult. |
+
Deadlines |
+The project is based on some deadline days when our work is presented |
+Very high |
+High |
+The team will follow the planification of the project to avoid problems on each one of the deadlines. |
+
The day when wikidata is outdated could come, and the app could still be working. It’s quite difficult but it could happen.
+The fact of using wikidata for retrieving the questions could mean that if the service of wikidata fails for some reason, the app would be failing as well.
+<Term-1>
<definition-1>
WIQ
A web application where users can register and login in order to play. The game consists on answering a number of questions with different types and subjects obtaining a prize for each question well answered.
Wikidata
It is a collaborative, free and open knowledge base that stores structured information. It aims to provide a common source of data that can be used by Wikimedia projects and anyone else, under a public domain license.
Saber y ganar
It is a Spanish television quiz show. It involves contestants competing in several rounds of questions to test their knowledge in different categories.
Diagram
A visual representation of information, data flow, processes, or systems using symbols, shapes, and lines to illustrate relationships, connections, and concepts.
Front-ent
Refers to the part of a software application or website that users interact with directly. It encompasses the user interface, design elements, and functionality visible to users.
Back-end
The behind-the-scenes part of a software application or website responsible for handling data processing, server-side logic, and database interactions. It includes the server, database, and application logic that users do not directly interact with.
Microservices
An architectural approach to building software applications as a collection of small, loosely coupled services. Each service is designed to perform a specific business function and can be developed, deployed, and scaled independently.
Stakeholder
Individuals or groups with an interest or concern in a project, product, or organization. Stakeholders may include any party affected by or involved in the outcomes of a particular initiative.
Docker
A platform for developing, shipping, and running applications in containers. It allows developers to package applications and their dependencies into standardized units called containers, providing a consistent environment for software deployment across different computing environments.
MongoDB
A popular open-source NoSQL database management system known for its flexibility, scalability, and ease of use. It stores data in a flexible, JSON-like format called BSON and is commonly used for applications requiring high-volume data storage and real-time data processing.
Svelte
A modern JavaScript framework for building user interfaces. Unlike traditional frameworks that require the runtime presence of a virtual DOM, Svelte shifts the work to compile-time, resulting in highly optimized and efficient code with smaller bundle sizes.
<Term-2>
<definition-2>
API (Application programming interface)
Set of rules and protocols that allows different software applications to communicate and interact with each other. APIs define the methods and data formats that applications can use to request and exchange information. They enable developers to access the functionality of other software components or services without having to understand their internal workings. APIs are commonly used to integrate third-party services, access data from remote servers, and build modular and interoperable software systems.