**Pedro Ramos**
*107348*
**Backend**
+  +
+ ++ The Backend technologies and their connections. +
+ +--- + + + +## Table of Contents + +- [Action Flow](#action-flow) + - [Table of Contents](#table-of-contents) + - [General Flow Description](#general-flow-description) + + + +--- + +## General Flow Description + +The **backend** is composed of multiple services and technologies that manage **three internal functions**: + - **Load Balancing** + - **Data Manipulation** + - **Data Persistance** + + The **data** is provided in the form of **HTTP requests** created by the **frontend** of the application. + + These requests are first intercepted by the **load balancer**, which will distribute all the incoming requests to a set of **API instances**. + + These instances will perform the necessary **data processing** and analysis and will provide the response back to the load balancer, which will promptly **foward the response** back to the initial **requester**. + + To **persist** and save the **data**, the API instances are connected to a set of **three main databases**. + Each database has a **distinct function**, that being for saving the **data models** (main database), saving the **provided files** (cloud storage) and finally saving the **configurations** of the instances and "magic numbers" (configuration database) \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Backend Implementation/2-load_balancer.md b/versioned_docs/version-1.2/The Backend Implementation/2-load_balancer.md new file mode 100644 index 00000000..25442a93 --- /dev/null +++ b/versioned_docs/version-1.2/The Backend Implementation/2-load_balancer.md @@ -0,0 +1,33 @@ +# Load Balancer ++  +
+ +--- + + + +## Table of Contents + +- [Load Balancer](#load-balancer) + - [Table of Contents](#table-of-contents) + - [NGINX](#nginx) + + + +--- + + +## NGINX + + For the **load balancer**, we chose to use a simple [**NGINX**](https://nginx.org/en/) configuration, that allows us to tune how the **distribution of work** is made between the **API instances** (round-robin, response time, etc) and does not introduce a large processing **overhead** into our system. + + Since the system is **user-based**, the backend must provide the responses in a **timely manner**, so any overhead introduced must be reduced to a minimum. + + NGINX also allows us to automatically **intercept and filter large files** as soon as the requests carrying them are received in the backend, preventing these files from taking up too much processing power to analyze. + +So with NGINX we can: +* **Balance the processing load** more efficiently across our API Instances; +* **Prevent large files** from having to be processed, discarding them as soon as possible; +* **Reduce the overhead** introduced into the system by other large load balancers. \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Backend Implementation/3-api_Instances.md b/versioned_docs/version-1.2/The Backend Implementation/3-api_Instances.md new file mode 100644 index 00000000..4fe39374 --- /dev/null +++ b/versioned_docs/version-1.2/The Backend Implementation/3-api_Instances.md @@ -0,0 +1,111 @@ +# API Instances ++  +
+ +--- + + + +## Table of Contents + +- [API Instances](#api-instances) + - [Table of Contents](#table-of-contents) + - [Why Python and FastAPI](#why-python-and-fastapi) + - [The FastAPI implementation](#the-fastapi-implementation) + - [Endpoints](#endpoints) + - [Models](#models) + - [Repositories](#repositories) + - [Utils](#utils) + - [Templates](#templates) + - [Tests](#tests) + + + +--- + +## Why Python and FastAPI + + For the API itself, we chose to use [**FastAPI**](https://fastapi.tiangolo.com/). + + This choice was heavily influenced by the fact that **all the code must be extremely well documented** and easy to change in the future. + + FastAPI also provides **more functionality** than some of its more "barebones" competitors (for example, **flask**), while **omitting most of the less used features** of more complex alternatives (for example, **django**). + + The option of creating a **Spring-based API** or choosing a programming language **other than Python** is not possible, as the code itself **must be able to be maintained** by people who may not have the specific knowledge to quickly apply the changes that might be needed in the future. + + **Future proofing** also had a large impact on our decision, as all the components of this project must be able to have perhaps even **decades of support**, since if just one of the components used is discontinued, the whole action flow will be disrupted, causing **problems in the whole pipeline**. + + Therefore, **Python** and **FastAPI** were chosen because of their **featuresets**, easy **maintainability**, relatively **proven** future, and good **performance**. + +--- + +## The FastAPI implementation + ++  +
+ + The final API codebase was divided into **multiple subsections**: + +--- + +### Endpoints + + The endpoints consist of all the **accessible functions of the API**, along with their parameters and responses. + + All the endpoint's documentation can be found on the **Swagger documentation** on the API itself, at [**localhost:8080/docs**](localhost:8080/docs) (the application must be on in order for this page to work). + + The endpoints consist of **CRUD** and **other functions** that operate on the **models** and **local files** that have been inserted into the backend. + +--- + +### Models + + The models are the **Python/Database** representation of the **real-life objects** that we are working with, providing a simpler and more clear approach to **data manipulation**. + + There are multiple models, for example: + - **User** Model; + - **Dissertation** Model; + - **Notification** Model; + - etc. + + Using the [**pydantic**](https://pydantic.dev/) library, all the models automatically apply **data consistency checks**, valid value checks, **default values**, etc for all the parameters and variables stored inside a given model object, allowing for a much **easier and cleaner code** implementation. + +--- + +### Repositories + + For **interacting with the main database**, a set of repository actions was implemented that allow the **abstraction** of the database components in the rest of the application. + + These repositories apply the necessary database operations to the main Database given a set of predefined parameters, and respond with the semi-processed outcome of the database. + + These are essential to **ensure that the database is not overloaded** with bad requests from other functions, that the database threads are used **efficiently** and that access to the database is **easy to alter**. + +--- + +### Utils + + The utils are a set of functions that provide **extended functionality** to other parts of the API. + + These functions include: + - **Authenticating** users; + - Creating and sending **email notifications**; + - Getting the **configurations** from the Configuration Database; + - Managing **local files** from the Filesystem; + - etc. + +--- + +### Templates + + These templates are used by [**Jinja**](https://jinja.palletsprojects.com/en/3.1.x/) and the API to **generate simple HTML code**. + + The generated file can then be sent to an **email notification** or used to **list all the data collected** throughout the year (useful for collecting information from the previous year for backups). + +--- + +### Tests + + The test portion is still to be implemented. \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Backend Implementation/4-databases.md b/versioned_docs/version-1.2/The Backend Implementation/4-databases.md new file mode 100644 index 00000000..c416defb --- /dev/null +++ b/versioned_docs/version-1.2/The Backend Implementation/4-databases.md @@ -0,0 +1,82 @@ +# Databases ++  +
+ ++ The database technologies utilized +
+ +--- + + + +## Table of Contents + +- [Databases](#databases) + - [Table of Contents](#table-of-contents) + - [Databases](#databases-1) + - [Main Database](#main-database) + - [File Storage](#file-storage) + - [Configuration Database](#configuration-database) + + + +--- + +## Databases + +For better **separation, maintainability, scalability and performance**, the persistence of data was divided into **three separate databases**. + +This allows the better utilization of each database's **core strengths** as they are needed in the multitude of tasks that the **API Instances** are required to perform. + +--- + +### Main Database + ++  +
+ + The **models** mentioned previously as well as most of the data processed are **saved in the Main Database**. + + Due to the **volatile** and **highly customizable** nature of these models, a database that could easily be adapted to new model formats was necessary. + + This means that the typical SQL databases are **not adequate** for our type of data structures, so a **[NoSQL](https://en.wikipedia.org/wiki/NoSQL) database was chosen instead**. + + Most NoSQL databases are much more recent than the SQL databases we are used to, and since all the components in this project must have certified **long term support**, the **[MongoDB](https://www.mongodb.com/) database was chosen**. + + MongoDB allows the **models to be changed without affecting the compatibility of old data models**, meaning that changes made to the database will still always allow for old data to be processed along with new data. + + Another key feature that drove our decision is the ability to easily convert a **mongoDB document into a JSON object** that could easily be natively worked on inside our python codebase, **without the need for complicated operations** such as joins, aggregations, etc... + +--- + +### File Storage + ++  +
+ + **Storing large files** (ex: PDF files from dissertations or dissertation logos) would take a lot of **I/O throughput** away from the rest of the Main Database as well as use a lot of the machine's available **storage space**. + + This means that another way of storing large singular files had to be chosen. + + For this, we used a **cloud storage system** that is included inside the machine's filesystem, which is then linked inside the necessary **docker volumes**. + + This allows the asynchronous storage and retrieval of files **without impacting the Main Database's** throughput capacity or performance. + +--- + +### Configuration Database + ++  +
+ + Since **there can be a lot of API Instances running at any given time**, changes made to the configuration must be made in such a way that all the instances must pick up the new changes as soon as they use them. + + So for **configurations and "magic numbers"**, we had to implement a place where all the instances could reach and get the necessary values. + + To do this, we chose to add a **[MariaDB](https://mariadb.org/) implementation** so that we did not have to worry about **concurrency** between all the instances and the data changes, as well as allowing all the configuration data to be **stored in the same, easy to edit file**. \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Backend Implementation/5-docker_kubernetes.md b/versioned_docs/version-1.2/The Backend Implementation/5-docker_kubernetes.md new file mode 100644 index 00000000..f5da40cf --- /dev/null +++ b/versioned_docs/version-1.2/The Backend Implementation/5-docker_kubernetes.md @@ -0,0 +1,93 @@ +# Docker And Kubernetes ++  +
+ ++ The containarization technologies utilized +
+ +--- + + + +## Table of Contents + +- [Docker And Kubernetes](#docker-and-kubernetes) + - [Table of Contents](#table-of-contents) + - [Docker Compose](#docker-compose) + - [Docker Containers](#docker-containers) + - [Docker Networks](#docker-networks) + - [Docker Volumes](#docker-volumes) + - [Kubernetes](#kubernetes) + + + +--- + +## Docker Compose + ++  +
+ + [Docker Compose](https://docs.docker.com/compose/) was used as the primary **container orchestrator**. + + Docker Compose allows us to define all the necessary deployment parameters, such as **ports**, **volumes** and image **versions**. + + It also allows us to **manage**, **launch** and **stop** all the containers at once. + +--- + +### Docker Containers + ++  +
+ + For the dockerization of our application, the following containers were defined: + - **Application** (frontend) + - **Api Instance** (multiple can be created at once) + - **Load Balancer** + - **MongoDB** + - **MariaDB** + +--- + +### Docker Networks + + Another advantage of docker compose is the ability to create multiple **separate networks between containers**. + + In our application the following networks were created: + - **frontend_network** (App ⇄ Frontend Server) + - **backend_network** (API Instances ⇄ Databases) + - **request_network** (Load Balancer ⇄ API Instances) + +--- + +### Docker Volumes + + Both MongoDB and the Cloud Service require the use of volumes, and the Cloud Service's volume must be **mapped to the host's filesystem** (bind volume). + + In our application the following volumes were created: + - **mongodbdata** (MongoDB Data) + - **file-bind** (Bind volume that utilizes the host's filesystem, which is then managed by the cloud server) + +--- + +## Kubernetes + ++  +
+ + A [Kubernetes](https://kubernetes.io/) implementation was **partially implemented**, but would require more work to be put into it in order to be production ready. + + The specific kubernetes distribuition used was the simpler [K3s](https://k3s.io/), providing all the required functionality at a smaller cost of setup time. + + Since the final production environment will only consist of a **single server**, the kubernete's main feature of load balancing between machines would not be of any use. + + The ability to **detect crashes on containers** and **relaunch the affected service(s)** is very useful to our application, but more discussion needs to be had in order to determine if this is a priority for our system. + + The final production version will include a **kubernetes file** which will launch the containers and do the appropriate load balancing, but more **testing must be done** in order to apply the changes to production. \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Platform/1-architecture.md b/versioned_docs/version-1.2/The Platform/1-architecture.md new file mode 100644 index 00000000..b37700f9 --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/1-architecture.md @@ -0,0 +1,9 @@ +# Architecture + +## Architecture Diagram + +A simple diagram to illustrate our architecture + ++  +
diff --git a/versioned_docs/version-1.2/The Platform/2-Deployment.md b/versioned_docs/version-1.2/The Platform/2-Deployment.md new file mode 100644 index 00000000..9d14dd93 --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/2-Deployment.md @@ -0,0 +1,9 @@ +# Deployment + +## Deployment and Structural Diagram + +A simple deployment diagram and infrastructure mapping + ++  +
diff --git a/versioned_docs/version-1.2/The Platform/3-Requirements.md b/versioned_docs/version-1.2/The Platform/3-Requirements.md new file mode 100644 index 00000000..693b83f6 --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/3-Requirements.md @@ -0,0 +1,91 @@ + +## Functional + +### Dissertation Management + +- The system must allow teachers to upload/edit/delete dissertation proposals; +- The system must allow students to show interest in multiple dissertations and accept only one; +- The system must allow administrators to accept or deny dissertation proposals by teachers. +- The system must allow teachers to add dissertation proposals and accept students for them; + +### User Management + +- The system should allow students to check their dissertation status and manage their proposals; +- The system should allow teachers to manage their proposals, check interested students and accept them for their proposals; +- The system should allow administrators to manage the dissertation season and manage the system's users. + +### User Authentication + +- The system should provide a login mechanism using UA's idp through OAuth2; +- The system should restrict user access to certain features based on their role (e.g., student, teacher, administrator). +- The system must do various checks based on user attributes to ensure that only authorized users can access certain features. + +### Search Functionality + +- The search feature should allow users to search for dissertations based on various criteria, such as title, advisor, courses, areas, publication date; +- The system should provide advanced search options such as filters and sorting. + + +### Notification System + +- The system will included a notification system to alert users about important events, such as new dissertations, acceptance of proposals, and changes in the status of a dissertation. + +### Workflow Automation + +- The system should automate approval workflows for dissertation proposals, ensuring that they are reviewed and approved by the appropriate parties before being published; +- Notifications should be sent to the relevant users when a proposal is submitted, approved, or rejected. + + +## Non-functional + +### Performance + +- The system should maintain consistent response times as the user base or data volume increases; +- The system should be able to handle an increasing number of transactions or requests per unit of time. + +### Scalability + +- The system should accomodate a growing volume of data without significant degradation in performance; +- The system should support horizontal scaling by distributing workloads accross multiple servers or nodes; +- The system should support vertical scaling by allowing the addition of more resources to a single server; +- Ensure that vertical scaling provides a proportional increase in performance. + +### Availability and Fault Tolerance + +- In the event of a server failure, the system should automatically redirect traffic to an available server in a short period of time, to minimize service disruption; +- The system shall achieve a minimum uptime of 99.99% over any consecutive 30-day period, excluding scheduled maintenance windows; +- The system should remain available and responsive in the event of component failures or increased load; +- There should be sufficient capacity to accommodate the failover of services without impacting performance. + +### Load Balancing + +- The system should distribute incoming requests evenly across multiple servers to ensure balanced resource utilization; +- Load balancers should scale seamlessly to handle increased network traffic. + +### Data Partitioning and Integrity + +- The system should be able to shard data effectively to distribute it accross multiple nodes. +- The system shall implement thorough input validation mechanisms to ensure that only valid and properly formatted data is accepted; + +### Security + +- Access permissions should be based on roles to ensure proper authorization (RBAC - Role-Based Access Control); +- All sensitive data transmitted over the network should be encrypted using secure protocols (e.g., TLS/SSL); +- Implement secure CORS policies to prevent unauthorized access from web applications. +- Define and enforce access controls for log files to ensure that only authorized personnel can view and modify logs. + +### Maintainability + +- The system shall be designed with a modular architecture, facilitating independent updates and modifications to specific components without affecting the entire codebase; +- All code modules and functions shall be adequately documented, providing clear explanations of their purpose, inputs, outputs, and usage to aid developers during maintenance; +- System configuration settings should be stored in easily modifiable and well-organized database, reducing the need for code changes to configure updates; +- Implement logging for all significant system events, errors and warnings; +- Log entries should include timestamps to facilitate the analysis of events over time; +- Logs should be stored centrally to facilitate easy monitoring and analysis; + +### Usability and User Interface + +- Include in the user interface common elements, such as navigation menus and buttons, should maintain consistent placement and behavior throughout the application, reducing cognitive load for users; +- Minimize the loading of UI elements, aiming for swift responses to user interactions to enhance perceived performance and usability; +- Provide clear and concise error messages that help users understand issues and guide them toward corrective actions; +- Incorporate inline help and tooltips strategically to provide additional information or guidance without cluttering the interface. \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Platform/4-UseCases.md b/versioned_docs/version-1.2/The Platform/4-UseCases.md new file mode 100644 index 00000000..96f219aa --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/4-UseCases.md @@ -0,0 +1,134 @@ +# Use Cases + +## Actors + +- __Student__ + - Makes use of the system as a potential user of the services provided by that system; +- __Teacher__ + - Makes use of the system as a potential user of the services provided by that system; +- __Admin__ + - Responsible for ensuring that the system is properly working, and intermediate contact between the other actors. + +## Use Case UML Diagrams + ++  +
+ +### Student + +1. Show interest in a dissertation - Select a dissertation and register as interested in the system; + +2. See all dissertations uploaded to the website - View all dissertation proposals in the form of a list, with the help of a search bar, get faster to specific dissertations; + +3. Confirm agreement with teacher/advisor - After acceptance of the teacher, confirm the interest in the dissertation; + +4. Remove interest in a dissertation - Remove the interest in a dissertation that was previously selected; + +5. View Status of dissertations that I have registered interest - Keep up with the status of the dissertations that I have shown interest in; + +6. Receive email notifications about my interest status updates - Receive email notifications about the status of the dissertations that I have shown interest in; + +### Teacher + +1. See all dissertations uploaded to the website - View all dissertation proposals in the form of a list, with the help of a search bar, get faster to specific dissertations; + +2. Add dissertation proposal - Add a dissertation proposal, composed of a file and metadata ( title, description, etc... ); + +3. View list of interested students in a dissertation - Be able to see the students that showed interest in a dissertation I proposed to choose a student to work with; + +4. Choose a student for the agreement - Finalize the proccess by confirming a student to work in a dissertation; + +5. Update data of a dissertation - Be able to update the data of a dissertation that I proposed, like description, title, file, etc; + +6. Remove a dissertation that belongs to me - Be able to remove a dissertation that I proposed; + +7. Receive email notifications about dissertations that I'm (co)orientating - Receive email notifications about the status of the dissertations that I have proposed, that I'm a co-advisor and the students that showed interest in them; + +### Admin + +1. See all dissertations uploaded to the website - Be able to see all the dissertations that are in the platform and, with the help of a search bar, get faster to specific dissertations; + +2. Accept or deny dissertation proposal - Accept or deny a dissertation proposal, sdepending on the quality of the proposal and other aspects that influence the decision to accept or deny it; + +3. Close and open the Dissertation Season - Be able to open and close the dissertation season, so that no more dissertations can be added for the respective academic year; + +4. Generate a list of dissertations, respective advisors and students - Generate a list of all the dissertations, their respective advisors and the students that are working on them; + +5. Be able to assign new admins, given enough permission - Choose new admins to help with the management of the system but not with the smae permissions as the original admin; + +6. Receive email notifications about new dissertations proposals that need to be accepted - Receive email notifications about new dissertations that were submitted, for me to either approve or deny them; + + +## User stories + +### Student + +1. As a student +I want to see a list containing all the dissertations that are available in the platform, with a search functionality to make it easier to find the ones that I am interested in; + +2. As a student +I want to know more about some dissertations that i am interested +so that i can select one; + +3. As a student +I want to know more about internship offers by DETI so that i can select an internship; + +4. As a student +I want to check the status of the dissertations im interested in +so that i can check if the teacher has accepted me as the student for it; + +5. As a student +I want to remove my interest in a specific dissertation that I choose earliear + +6. As a student +I want to receive email notifications about the status of the dissertations that I have shown interest in + +7. As a student +I want to check regularly the status of the dissertations that I have shown interest in and others. + +### Teacher + +1. As a teacher +I want to see all the dissertations that are present in the platform, so that I can see the ones that I proposed and the ones that other teachers proposed, with search feature for me to speed up the proccess to find dissertations; + +2. As a teacher +I want to be able to add the dissertations proposal's that I'm going to guide in that year, (could be or not co-supervised) so that student's can then read and show interest on them; + +3. As a teacher +I want to confirm the agreement between me and the student that confirmed interest on my proposal so that the next steps can be taken; + +4. As a teacher +I want to be able to update the data of a dissertation that I proposed, like description, title, file, etc; + +5. As a teacher +I want to be able to remove a dissertation that I proposed; + +6. As a teacher +I want to be able to see the students that showed interest in a dissertation I proposed to choose a student to work with; + +7. As a teacher +I want to receive email notifications about the status of the dissertations that I have proposed, that I'm a co-advisor and the students that showed interest in them; + +### Admin + +1. As an admin +I want to see if there are any unapproved dissertations proposed by supervisors so they could be seen by all student's, after my approval; + +2. As an admin +I want to be able to close and open the dissertation season, so that no more dissertations can be added for the respective academic year; + +3. As an admin +I want to be able to introduce/change features in the system so that the system can be improved and updated; + +4. As an admin +I want to be able to generate a list of all the dissertations, with their respective advisors and the students that are working on them so that I can send it to the academic services of the university; + +5. As an orignal admin +I want to be able to assign new admins, given enough permission to obtain more help with the management of the system but not with the same permissions as me; + +6. As an admin +I want to receive email notifications about new dissertations that were submitted, for me to either approve or deny them; + +7. As an admin +I want to see all the dissertations that are in the platform and, with the help of a search bar, get faster to specific dissertations. \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Platform/Prototype.md b/versioned_docs/version-1.2/The Platform/Prototype.md new file mode 100644 index 00000000..4518d93a --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/Prototype.md @@ -0,0 +1,17 @@ +#### Prototype link: https://www.figma.com/file/JLCHHMr9t78a8Ez7kj5uzy/Protótipo?type=design&node-id=0-1&mode=design&t=u19e9mVM6SQowtC4-0 + +Add dissertation: ++  +
+ +See list os dissertations: ++  +
+ +List all dissertations by a teacher: + ++  +
diff --git a/versioned_docs/version-1.2/The Platform/Usability Tests.md b/versioned_docs/version-1.2/The Platform/Usability Tests.md new file mode 100644 index 00000000..7b759114 --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/Usability Tests.md @@ -0,0 +1,77 @@ +## Heuristic Evaluation + +In order for us to achieve a renewed platform, while keeping it simple and usable, we performed an heuristic evaluation on the existing platform. Despite being quite old, we were amazed by its usability. + +We followed the Jakob Nielsen’s 10 usability heuristics to evaluate the platform. This evaluation method suggests five evaluators as the "magical number" to perform a good heuristic analysis, so all of our team (five people) performed and evaluation. The results are listed bellow. + +## On the old platform +### Problems +| Problem | Description | Heuristic | Severity | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------- | +| Ambiguity in Application Functionality Display | Even with multiple of the functions of the application being disabled or non-functional, they still appear on the website, leading to confusion about the functionalities available. | Error prevention #5 | 3 | +| Cluttered Design | The design is very cluttered and does not feel easy to use for someone with no prior experience. | Aesthetic and minimalist design #8 | 4 | +| Dissertation Creation Form | The dissertation's creation/edition form does not scale well with the number of options available. There isn't much space between each field, which can be overwhelming. | Consistency and standards #4 | 2 | +| Order of columns in different pages | The columns aren't consistent between the main dissertation list and teacher's dissertation list. Despite that, teacher's dissertation list has a weird order and spacing of columns. | Consistency and standards #4 | 3 | +| Uniformity Across Platform | Most of the pages are focused on one center table that shares its look across all of the platform, leading to many pages looking exactly the same despite having completely different data and usage. | Match between system and the real world #2 | 4 | +| Repeated Taks | The website itself is "clunky" to use and does not provide a very efficient way of automatic certain tasks, especially for the teachers. | Flexibility and efficiency of use #7 | 2 | +| Non-Adaptative layout | The platform doesn't account for smaller screens and its fixed at a 16:9 ration. Smaller screens have content cutted and have to scroll. | Flexibility and efficiency of use #7 | 2 | +| Extra menus and information | Pages contain irrelevant information (like the landing page), or empty pages. The side menu has irrelevant tabs. | Aesthetic and minimalist design #8 | 3 | +| Inconsistent Data Presentation in Dissertation List | The dissertation list table presents data in an unusual order, prioritizing courses over dissertation titles. Additionally, the checkbox indicating whether a dissertation is chosen is small and difficult to notice. | Match between system and the real world #2 | 2 | +| Confusion in Academic Year Navigation | On the teachers' "Dissertações submetidas" page, the title correctly displays the academic year of the dissertations shown. However, above the legend, two different academic years are displayed, potentially confusing users about the data shown. | Flexibility and efficiency of use #7 | 3 | +| Lack of Contextual Awareness in Table Design | Most pages use tables to display data, but the table format remains consistent regardless of the data shown, forcing users to rely on page titles or table content to understand their current location and context. | Error prevention #5 | 2 | +| Confusion in Academic Year Navigation | On the teachers' "Dissertações submetidas" page, the title correctly displays the academic year of the dissertations shown. However, above the legend, two different academic years are displayed, potentially confusing users about the data shown. | Flexibility and efficiency of use #7; Visibility of System Status #1 | 3 | +| Lack of Clarity in Initial Login Error Message | The initial login only indicates a problem with the account without specifying the nature of the issue, potentially confusing users who are unsure if the problem lies with their access or another issue. | Help Users Recognize, Diagnose, and Recover from Errors #9 | 3 | +| Visibility Discrepancy in Dissertation Selection | In the dissertations list, some dissertations appear as not chosen (unchecked tick box), but when users click to view more info ("Ver"), they appear as chosen ("Escolhida:Sim"). | Visibility of System Status #1 | 3 | +| Non-Adaptative layout | The platform doesn't account for smaller screens and its fixed at a 16:9 ration. Smaller screens have content cutted and have to scroll. | Flexibility and efficiency of use #7 | 2 | +| Captions instead of recognizable icons/terms | The platforms displays information as a table, and some elements, like in the "Lista de Interessados" page, columns are represented as non-recognizable icons and require a caption | Recognition Rather than Recall #6 | 3 | +| Sidebar Design | The sidebar design lacks organization and spacing, displaying too much information in a cluttered manner. It should be better organized and spaced, with options that are relevant and properly displayed. | Match between system and the real world #2 | 4 | +| Extra information | Pages contain irrelevant information (like the landing page), or empty pages. | Aesthetic and minimalist design #8 | 3 | + +### Strengths + +| Strength | Description | Heuristic | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| New Dissertations | There is a very noticeable visual hint indicating if a dissertation is new, so users can easily distinguish which dissertations have been added since they last visited the platform. | Recognition Rather than Recall #6 | +| Error on bad Login | When we, has students of the 3rd year try to login in the website a good error message appears saying that there is a problem with our account and a way to fix it is to talk to the secretary, this message is good but it could be better saying like you don't have access to the website and explain the reason | Error prevention #5; Help Users Recognize, Diagnose, and Recover from Errors #9 | +| Intuitive buttons | Every action button is very intuitive, so users can easily figure what it does. | Recognition Rather than Recall #6 | +| Descriptive legends | Every icon has an associated legend to help lost users to understand the meaning of the column/ field | Help and Documentation #10 | +| Simple Design | The website keeps a simple design (maybe way too simple).The website's information and options are laid out in a way that makes sense (side menus, main table, sort and pagination above) and displays all the necessary information accordingly (but cluttered). | Aesthetic and minimalist design #8; Recognition Rather than Recall #6 | +| Support contacts | Some pages provide a contact to the support team, which can help the user to solve the problem. Most pages also contain a legend to help the user understand the data presented on the tables. | Help and Documentation #10 | +| Captions on icons | The caption that appears, helps the user to know more of how the website is organize | Help and Documentation #10 | +| Consistent vocalbulary | Every term used in the website seems to be in accord with the standards, and it's consistent throughout the platform | Consistency and standards #4 | +| Easy Navigation | Getting in and out of pages is very simple, as well as navigate to desired pages | User Control and Freedom #3 | + +## On the prototype +After performing the heuristic evaluation on the old platform, we started working on our prototype. +As humans, we aren't impune from making bad decisions, so we performed an heuristic evaluation on the prototype. Despite correcting most of the flaws presented by the old platform, we ourselves did our fair quote of usability errors. The results are listed bellow. + +### Problems +| Problem | Description | Heuristic | Severity | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | -------- | +| Power-user only search | he search bar is heavily focused on power-users, mainly when applying filters. Basic users will have much more difficulty in applying filters | Flexibility and efficiency of use #7 | 4 | +| Hidden dissertations when user has many alerts | As the "As minhas Dissertações" tab is under the alerts tabs, when it has a lot of notifications it hides the underling tabs. | Visibility of System Status #1 | 3 | +| Extra effort to make an action | In order to accept a dissertation, the admin has to access his profile and then see the list of dissertations. The same happens if a teacher wants to see the list of interested students, he has to access the dissertations and only then see the interested students. | Flexibility and efficiency of use #7 | 3 | +| Overall Design | The aplication still needs to provide a more consistent layout that is both simpler and less clutterred. | Consistency and standards #4 | 3 | +| Lack of errors | More errors and notifications should be added in order to let the user know any mistakes made from his options or from problems with the application. | Help Users Recognize, Diagnose, and Recover from Errors #9 | 3 | +| Position of important buttons | When its presented to a student an agreement to accept a dissertation the options to accept or deny it are in the end of the page and it should be the main focus meaing that it should appear at the end of the page and in the notification it could appear the options to accept or deny it plus the see more option. | Flexibility and efficiency of use #7 | 3 | +| Inconsistent Labeling | Where it shows As minhas escolhas it shoukd appear a different label, depending on the role, like for student it should appear Dissertações com interesse or if he/she already has one dissertation appear Dissertação Escolhida or Atribuída, for a teacher As minhas dissertações is a correct label and for admin it could appear Dissertações pendentes; | Consistency and standards #4 | 4 | +| Lack of Useful Navigation | In the student's profile page t it's missing a quick access button saying "Ver mais dissertações" for the student to add more interest on dissertations, the same goes for the admin navbar, where it's missing a quick access link to see the dissertations that are waiting for approval; | Flexibility and efficiency of use #7 | 2 | +| Role not Displayed | The website doesn't show the user role on the navigation bar , which can lead to confusion about the user's permissions and what he can do on the platform. | Visibility of System Status #1 | 2 | +| Too Many Colors | The amount of different colors and saturation used in the dissertation list page may lead to a unpleasent experience for the user, as it is difficult to focus on the data presented. Colors with more "pop" should be preserved for more important information, while things such as Courses of a dissertation shouldnt use such a strong color. | Aesthetic and minimalist design #8 | 3 | +| Easily Cluttered Layout | The current layout of "Áreas" and the dissertation course are not scalable and may lead to a cluttered UI if more options are added without adjustments done. Same problem for the dissertation details page. Same problem for profiles pages. | Aesthetic and minimalist design #8 | 4 | +| No Captions | There is no legend to indicate what is the green background on the new dissertations list, which may lead to confusion about the meaning of the color. | Help and Documentation #10 | 2 | +| Extra information and inconsistent layout | In the "Profile Student Page Accepted Acordo", the text is not all justified to start on the same position. Curso(s) is also irrelevant information in this page. | Aesthetic and minimalist design #8 | 2 | + +### Strengths + +| Strength | Description | Heuristic | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| Clean Layout | The application provides a clean landing page that clearly states the purpose of the application and next steps to be taken by the user in order to achieve his goals. The contrast of the new dissertations makes them easily spotted. | Match between system and the real world #2 | +| Easy Navigation | The search bar provides a quick way to find wanted dissertations, thats intuitive and doesnt require a lot of clicks from the user. | Flexibility and efficiency of use #7 | +| Consistent Color Scheme | The website has a consistent color scheme throughout the pages, which helps the user to understand the importance of the information presented. | Consistency and standards #4 | +| Descriptive Layout | Users can easily see all the crucial information they need with a glance of an eye. | Aesthetic and minimalist design #8 | +| Alerts on Action | When the user makes an important action an alert is shown. This prevents user from making wrong actions and giving confirmation on successful actions. | User Control and Freedom #3; Visibility of System Status #1 | + +After compiling the results, we returned to the design table to correct our usability flaws. + +> **All heuristic evaluation reports can be found in our drive** \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Platform/_category_.json b/versioned_docs/version-1.2/The Platform/_category_.json new file mode 100644 index 00000000..4f001900 --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "About the platform", + "position": 3, + "link": { + "type": "generated-index", + "description": "This section provides an overview of the platform and its features. It describes the platform's requirements (as user stories and use cases), architecture and tech stack (and why we choose it)." + } +} diff --git a/versioned_docs/version-1.2/The Platform/tecnologies.md b/versioned_docs/version-1.2/The Platform/tecnologies.md new file mode 100644 index 00000000..29a7466f --- /dev/null +++ b/versioned_docs/version-1.2/The Platform/tecnologies.md @@ -0,0 +1,58 @@ +# Tech Stack + +In order to accomplish one of our goals - _make the platform easy to maintain and make it as durable as possible_ - we did an exhaustive research on the topic of **Tech Stack**. +To make it easier to visualize and make an informed decision, we elaborated these **tables** with essential information, such as the _date of the **last commit**_, _the **purpose** of the technology in our project_ and the _**companies** behind each technology_. + +## FrontEnd Tech Stack + +This table contains all our proposals for the frontend tech stack. + +> **Note for navigation:** +> While navigating thought the table, you might spot a ⚠️ near the technology name. It indicates that there is more than one technology that serves the same purpose in our proposal. We clarify our choice after the table. + + +| Technology | Github | Purpose in Project | License | Community | Date of creation | Last Commit | Owner/ Famous companies using | +| ------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ | --------- | ----------- | --------------------------------------------------------------------------------------------------- | +| [React](https://react.dev) ✅ | https://github.com/facebook/react/releases | JavaScript library | MIT License | **218k** stars in github, **21.7m** weekly npm installs | 2013 | 19 jan 2024 | Facebook | +| [vite](https://vitejs.dev) ✅ | https://github.com/vitejs/vite | Tool for creating and setting up React projects | MIT License | **62.6k** stars in Github, **9.4m** weekly npm installs | 2019 | 19 jan 2024 | Sponsored by Astro, StackBlitz, NuxLabs, JetBrains, TailwindLABS,... | +| [daisyui](https://daisyui.com/) ✅ | https://github.com/saadeghi/daisyui | Pure CSS component library for Tailwind. | MIT License | **28.4k** stars in github, **165.3k** open source projects, **227.9k** weekly npm installs | 2021 | 15 jan 2024 | None | +| [tailwind](https://tailwindcss.com) ✅ | https://github.com/tailwindlabs/tailwindcss | CSS library | MIT License | **75.5k** stars in github, **7.9m** weekly npm installs | 2017 | 19 jan 2024 | TailwindLABS: used to build GitHub Next, Microsoft .NET, OpenAI / ChatGPT and many more websites. | +| [axios](https://axios-http.com) ✅ | https://github.com/axios/axios | Library for exchanging HTTP-based promises to make requests to the API. | MIT License | **103k** stars in github, **47.3m** weekly npm installs | 2014 | 5 jan 2024 | AXIOS; Sponsored by Lowdify, Proxidize, ... | +|[formik](https://formik.org) ⚠️ | https://github.com/jaredpalmer/formik | Library for creating and managing forms | Apache License 2.0 | **33.2k** stars in github, **2.3m** weekly npm installs | 2017 | 17 set 2023 | Formium; Used in companies such as Walmart, NASA, Docker, Bookingcom, ... | +| [react-hook-form](https://react-hook-form.com) ✅ | https://github.com/react-hook-form/react-hook-form | Library for creating and managing forms | MIT License | **38.4k** stars in github, **4.2m** weekly npm installs | 2019 | 16 jan 2024 | Supported and Backed by BEEKAI, Vercel | +|yup ✅ | https://github.com/jquense/yup | Library for form validation | MIT License | **27,1k** stars on github, **5.1m** weekly npm installs | 2014 | 9 jan 2024 | None -> Used side by side with Formik or other React form libraries | +|[zustand](https://zustand-demo.pmnd.rs) ✅ | https://github.com/pmndrs/zustand | Library for state management within the React application | MIT License | **39.1k** stars in github, **2.9m** weekly npm installs | 2019 | 31 dez 2023 | None: Used by companies like Hotjar, RippleAI, ... | +|[redux toolkit](https://redux-toolkit.js.org) ⚠️ | https://redux-toolkit.js.org | Library for state management within the React application | MIT License | **10.2k** stars in github, **2.9m** weekly npm installs | 2015 | 19 jan 2024 | ReduxTeam; Used by many companies like Instagram, Amazon, ... | +| [React Router Dom](https://reactrouter.com/en/main) ✅ | https://github.com/remix-run/react-router | Library for client side routing | MIT License | **51.7k** stars in github, **10.1m** weekly npm installs | 2014 | 18 jan 2024 | Remix | + +_consulted on January 19, 2024_ + +Regarding the choice between the state management libraries we propose, **Redux** and **Zustand**, we decided to use zustand in our project for 2 main reasons: +- zustand provides less boilerplate code than redux, making our codebase more concise and more maintainable, which aligns with our goals; +- zustand minimal api feels more natural to react development, as it uses react hooks to create and manage stores *(while making the whole process faster)* + +Regarding the forms management libraries, **react-hooks-form** and **formik**, we opted to use react-hooks-form, mainly because formik's last commit was more than 3 months old (at the time) and has more had more than 600 issues open on github. As one of our goals is to enhance DSD's maintainability and longevity, we decided to use a newer and more maintained react-hooks-form. + +## BackEnd Tech Stack + +# Table with proposed backend technologies for the project. + +This table serves for choosing between two technologies for two different applications: + +- MongoDB driver: pymongo or motor; +- SAML implementation library: pysaml2 or python3-saml. + +**Notes:** + +- Motor is a pymongo wrapper that uses a set of threads which can help overcome I/O bottlenecks related to database access. This performance increase is only applicable to some cases, so some tests will need to be conducted to analyze its relevance for this project; +- python3-saml is a library more focused on communication with an existing Identity provider, while pysaml2 is a more comprehensive library (can serve as an Identity provider) but whose extra functionalities will not be useful for this project. + + +| Technology | Github | Purpose in Project | License | Community | Date of creation | Last Commit | Owner/ Famous companies using | +| ---------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------- | --------- | ----------- | ------- | +| [pymongo](https://www.mongodb.com/docs/drivers/pymongo/) | https://github.com/mongodb/mongo-python-driver | Driver síncrono de mongoDB para python | Apache License 2.0 | **4k** stars in github, **1.2k** forks, **145** contribuidores | 2019 | 23 jan 2024 | MongoDB | +| [motor](https://motor.readthedocs.io/en/stable/) ✅ | https://github.com/mongodb/motor | Driver assíncrono (non-blocking) de mongoDB para python que usa o pymongo e um sistema de multi-threading | Apache License 2.0 | **2.3k** stars in Github, **217** forks, **46** contribuidores | 2019 | 16 jan 2024 | MongoDB | +| [pysaml2](https://idpy.org//) | https://github.com/IdentityPython/pysaml2 | Implementação 100% python do Standard SAML Version 2 com capacidades de implementar ambos um Service provider e Identity provider (não necessitado neste projeto) | Apache License 2.0 | **534** stars in Github, **455** forks, **135** contribuidores | 2013 | 7 nov 2023 | None | +| [python3-saml](https://github.com/SAML-Toolkits/python3-saml) ✅ | https://github.com/SAML-Toolkits/python3-saml | Livraria de implementação do SAML focada na simplicidade e eficiência, permite criar apenas um Service provider | MIT License | **636** stars in Github, **337** forks, **65** contribuidores | 2016 | 1 nov 2023 | None | + +_consulted on February 8, 2024_ \ No newline at end of file diff --git a/versioned_docs/version-1.2/The Problem/_category_.json b/versioned_docs/version-1.2/The Problem/_category_.json new file mode 100644 index 00000000..30bd85e8 --- /dev/null +++ b/versioned_docs/version-1.2/The Problem/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "About the project", + "position": 2, + "link": { + "type": "generated-index", + "description": "This section provides an overview of the project and its goals. It also includes information about the project's context." + } +} diff --git a/versioned_docs/version-1.2/The Problem/index.md b/versioned_docs/version-1.2/The Problem/index.md new file mode 100644 index 00000000..5f130520 --- /dev/null +++ b/versioned_docs/version-1.2/The Problem/index.md @@ -0,0 +1,12 @@ +--- +sidebarPosition: 2 +--- +# Context and State of The Art (SOA) + +In the context of dissertation and internships choice, nowadays Aveiro University (UA) has different ways to deal with this problematic. In the Department of Electronics, Telecommunications and Informatics (DETI), this choice is being supported by a platform developed by a group of DETI students in the 2000s, which is available at http://sd.web.ua.pt. + +Over the years, no additional features have been developed and maintenance has been minimal, which lead to a platform that has a outdated UI, untapped bugs, growing security vulnerabilities and technologies that are less used, such as aspx in old versions of ASP.NET, that is a server-side web-application framework designed for web development to produce dynamic web pages. + +With this concepts in mind, the objective of this project is to overhaul the existent platform to manage amongst other things the publicity and bidding process of dissertations in the MSc taught by DETI. + +The new platform should provide a renewed interface and functionalities to assist both teachers and students in advertising and choosing their final dissertation projects. \ No newline at end of file diff --git a/versioned_docs/version-1.2/intro.md b/versioned_docs/version-1.2/intro.md new file mode 100644 index 00000000..0d23a6f7 --- /dev/null +++ b/versioned_docs/version-1.2/intro.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 1 +--- + +# Welcome + +📚 **Welcome to our documentation section!** 🚀 + +We're thrilled to have you here as we embark on this journey together. In this documentation, you'll find everything you need to know about our project, from its inception to its current state. 🌟 + + +## Our Team ✨ + +|
