1. Introduction and Goals
The software development company HappySw has been hired by the Council of Brussels to develop a software system called LoMap. This system will allow citizens to have personalized maps of places and local businesses in their city. The places that can be mapped include restaurants, parks, shops and cultural attractions, among others. Users will have full control over their personalized locations and the shared information will be stored in a personal pod according to the SOLID project.
HappySw’s goal is to develop a generic software solution that can be deployed and used in other places. The initial focus of the project is on the user, allowing them to create their own personal map of the places they live. The next step could be to allow places such as shops, restaurants, etc. to create their own digital spaces.
The software development project aims to create a system that meets the underlying business goals, essential features, and functional requirements. The architecture of the system must also meet specific quality goals, which are of utmost importance to the major stakeholders (especially the Happy Software project management). The relevant stakeholders and their expectations must also be considered during the development process, as well as some optional requirements which implementation could be studied.
As the software architects and developers of the LoMap aplication we must take into account the following issues:
-
Business Goals: On request of Brussels' Council, LoMap has to provide citizens with personalized maps about local places and business. Regarding to the enterprise’s expectations, the software solution should aim to be general enough to be adapted to other future projects.
-
Quality Goals for the Architecture:
-
The information about a place should be stored in each user’s personal pod.
-
Security and respect for user privacy.
-
Responsiveness of the application.
-
Originality of the solution.
-
The system should also have a continuous integration and continuous delivery strategy and should be interoperable between the data stored by different applications with similar goals.
-
Relevant Stakeholders and Expectations: The stakeholders in the LoMap project include the Council of Brussels, HappySw, and the citizens of the city who will be using the software system. The Council of Brussels expects a software solution that will provide citizens with personalized maps about places and local businesses in their city. HappySw is expected to develop a generic software solution that can be deployed and used in other cities in the future. The citizens are expected to have an easy-to-use and responsive software solution that respects their privacy and allows them to create personalized maps about places and local businesses.
2. Requirements Overview
We expect the future users of the application to use it as a simpler and more friendly version of other mapps such as Google mapps, for example. Additionally, it will offer solid references of what can be expected from the city (as a general overview) and the sites that the users may introduce, post, comment, advise, etc…
-
The LoMap system must allow users to add locations in different categories such as shops, bars, restaurants, sights, monuments, etc.
-
It should also enable users to show the locations on a map window and add review scores, comments, pictures, etc. about the added places.
-
The system must allow users to manage the information accessible by other users.
-
The LoMap system must prioritize the aesthetics and usability by non-technical people.
-
Quality of technical documentation
-
Code quality and tests code coverage.
3. Quality Architecture Goals
-
The information about a place should be stored in each user’s personal pod.
-
Security and respect for user privacy.
-
Responsiveness of the application.
4. Stakeholders
| Role/Name | Contact | Expectations |
|---|---|---|
Brussels Council |
Fatima Abid |
Keep the power in the next elections |
Happy Software |
Jose Emilio Labra Gayo |
Earning a lot of money and getting a polivalent software solution |
Developement Team |
Winning the SOLID tournament |
-
Brussels Council: The final solution is bound to be evaluated in terms of the popular satisfaction with the product.
-
Happy Software: It is neccessary that the solution keep the bosses satisfyed in every aspect of the project. Documentation will be a determinant factor as long as other techincal oriented people will certainly evaluate the work performed. It is particularly important that the architecture satisfyes their requirements.
-
Developement team: Must discuss and come up with ideas and solutions related to the architecture, design, system… Of course deep knowledge about the entire software is mandatory.
5. Architecture Constraints
5.1. Technical constraints
Constraint |
Explanation |
SOLID |
SOLID pods will be used to store the data. |
Docker |
The application is to be deployed using docker. |
GitHub |
GitHub will be used as a git host. Through this, we will manage version control, communication, actions and the project itself. |
5.2. Organizational and political constraints
| Constraint | Explanation |
|---|---|
Team composition |
The team will consist of 2 members with a small and limited experience in the technologies that will be used. |
Meetings |
In each laboratory, there will be a meeting to discuss the next week tasks. In case of any extraordinary meeting to be needed, it will be agreed byboth of us and recorded in the activity. Those minutes will be found here here. |
Comunication |
Taking advantage of being working in such a small team, the comunication between the members can be done very easily. However, we have to be able to persist the important decisions regarding the project. |
Testing |
There will be different scenarios that will test the proper behaviour of the application. |
Deliveries |
To check on the project progress there will be several deliveries through the time. |
5.3. Conventions
| Constraint | Explanation |
|---|---|
Documentation |
It will be used Arc32 template for keeping a simple and clean documentation. |
Clean code |
The code must be clean and well written to keep it easier to work with and mantain. |
Accessibility |
The interface must be easy to understand and to navigate through for every possible non-technical user. |
SOLID |
The code must follow the Solid project conventions. |
Language |
We will try that the most part of the official contribution to the project is done in english so it is the most global possible. |
6. System Scope and Context
6.1. Business Context
| Entity | Input | Output |
|---|---|---|
User |
The user interacts with the application through a computer or device using the front-end of the application. |
The result is displayed in various parts of the system, satysfying the high level requirements of the project. |
User POD |
Receives requests to modify or obtain personal information and locations created by the user. |
Stores and/or returns the information requested by the user. |
LoMap System |
The user interacts with this system by sending requests through the interface. |
It processes incoming requests, manages the data to ensure consistency, and then displays the requested information to the user via the interface. |
6.2. Technical Context
According to the SOLID project, shared information will be stored in each user’s POD in order to preserve the privacy of the data. In addition, we will implement the application using TypeScript together with React. Besides, different types of tests are going to be necessary. Finally, it is mandatory to tell that the LoMap system is going to use the Google Maps API in order to provide the service of the map in the application.
| Technology | Explanation |
|---|---|
TypeScript |
The programming language used for development. |
React |
JavaScript library used for Front-end development. |
NodeJS |
Server environment used for the application. |
7. Solution Strategy
7.1. Technology decisions
We are using the following technologies for the development of the application:
-
Solid. Specification that lets people store their data securely in decentralized data stores called Pods. This was a constraint.
-
React. A open-source JavaScript library for building user interfaces. We use it since it is easy to lern, its high performance and the high demand of this technology.
7.2. Decisions about the top-level decomposition of the system
-
We are starting this project from the public template Arquisoft/lomap_0
7.3. Decisions on how to achieve key quality goals
Quality goal |
Approach |
Security and Privacy |
SOLID pods will be used to store the user data securely in a decentralized way. |
Responsiveness |
React will be used for achieving a responsiveness web application. |
Maintanability |
The code will be clean, avoiding bad smells. |
Scalability |
The project has to be easy to interact with, in order to be easy to add functionality (i.e.: the optional requirements) |
7.4. Relevant organizational decisions
-
Language: As said before, the prefered language for contributions to the project is set to be english as we intend that this project can reach the more people the better.
-
Issues: Although being just two people enables quick and instant comunication thorugh different tools, we have to try to reflect the actual issues of the project in the repository.
-
GitHub Projects: We intend to use the GitHub project to organize the work that is to be done, has been done or is being done.
8. Building block view
8.1. Level 1
- Contained Building Blocks
| Name | Description |
|---|---|
User |
Who uses the application. |
LoMap application |
Contains the front-end tools that will be served to the user and integrates them to extract the SOLID necessary data to function properly. |
Pod service |
Responsible for accessing each user’s personal POD and storing their information. |
8.2. Level 2
- Contained Building Blocks
| Name | Description |
|---|---|
User Interface |
Through it, the user will be able to perform any task in the system and will receive the appropiate results. |
Data access layer |
Layer providing simplified access to data stored in persistent storage, which will enable the user to access the information of himself and his friends. |
8.3. Level 3
- Contained Building Blocks
| Name | Description |
|---|---|
Views |
Parts of the application where the user will interact with the system. |
Sign up |
Allows the user to create an account. This process happens only once per user. |
Sign in |
Allows the user to log in with their account, if they have already created one. |
Log out |
Allows the user to log out. |
Home |
Initial tab of the application. Displays a welcome message. |
Map |
Tab that displays a map and allows to manage the user’s locations. |
My ubications |
Tab showing a short description of the locations created by the user. |
My friends |
Tab for managing the user’s friends |
9. Runtime View
9.1. Login
When an unidentified user logs in.
9.2. Seeing a personalized map
When an identified user sees a personalized map. Note that in our project, by the way, the map provider is Google maps.
9.3. Friend’s Management
The application enables the user to modify its list of friends from Solid. Note that the relation between people in this plataform are not bidirectional, so that is how they work in LoMap too.
10. Deployment View
10.1. Infrastructure Level 1
- Quality and/or performance features
-
The performance and quality of the application are influenced by factors such as internet connection and hardware of the user’s device, as well as the Azure server device, which we have no control over. However, we will optimize the application to maximize its performance and quality, using the best available technologies to minimize user waiting times. Our main goals are to ensure privacy, usability, and maintainability.
Regarding the infrastructure, the WebApp is the frontend and backend of the application, which is rendered by a web browser on the user’s device. The SOLID PODs will be provided by the Solid Community, responsible for offering the pods to the users. However, following the Solid principles, the application should be independent from the PODs provider selected by the user. Lastly, the client device is the device used by the user, which must have an internet connection to use the application.
- Mapping of building blocks to infrastructure
| Element | Description |
|---|---|
WebServer |
Where the app will be hosted. |
WebApp |
The frontend of the app that will be displayed on the browser. |
POD Provider |
Provider of the pods to be used. |
MapProvider |
API that will be used to display a map. Right now we are working with Google Maps |
11. Cross-cutting Concepts
11.1. Domain
-
Location: The application revolves around the concept of locations, which can be shops, bars, restaurants, sights, monuments, etc. Users can add locations to their personalized map, along with review scores, comments, pictures, and other information. Additionally, places can create their own digital space, allowing people to connect with them and receive recommendations.
-
Personalized maps: The application allows users to create their own personalized maps, with the locations they are interested in. Users can manage the information that is accessible to other users, such as their friends or groups of friends. The information about a place stored by each user is stored in each user’s personal pod, according to the SOLID project.
11.2. User Experience
-
Personalized maps: The ability for users to create their own maps of the places they live or visit, which puts the focus on the user and their preferences. Besides, users are thought to have full control over the mapps they create.
-
Map filters: The ability for users to filter the map by category, friends, and other criteria, which helps them find the places they are interested in more easily.
11.3. Safety and security
-
Privacy: The application must ensure the privacy of its users. The information about a place stored by each user should not be centralized and should be stored in each user’s pod. If it is considered necessary, the system could store other information in a centralized way for performance reasons trying to respect the privacy of the users as much as possible. Security is a quality goal for the architecture, and the system must respect the privacy of the users.
-
Access control: The system must have appropriate access controls in place to ensure that only authorized users can access and modify personal and shared data.
-
Secure data storage: The system must ensure that data stored in user pods and other centralized data stores is secure and protected from unauthorized access.
11.4. Architecture and design
-
Personal pod: This refers to the storage location where the information about a place is stored by each user. It is a decentralized storage location and the information is owned and controlled by the user, which enhaces security and privacy.
-
Centralized storage: In some cases, it might be necessary to store information about a place in a centralized way for performance reasons. This should be done while respecting the privacy of the users as much as possible. Apart from the security policy, an application is bound to be efficient in its response if it wants to be util for users.
-
Interoperability: The solution must be designed in a way that allows for interoperability between the data stored by different applications. This means that the system should be able to integrate and work with other systems and applications that might be used by stakeholders or other parties.
11.5. Implementation
-
Testeability: The implementation must be able to be tested. Not only must we test the ability of the application to perform the appropiate operation, but also the degree in which the quality scenarios are satisfyed.
-
Maintenance: This refers to the activities performed to keep the system running smoothly and to address any issues that may arise. It can include tasks like patching, upgrading, and bug fixing. In order to keep the maintenance of the project under control, we must proceed very carefuly with the developement of the application and keep our code under high level of quality.
-
Reliability: This refers to the ability of the system to function without failure or downtime. It involves designing the system in a way that minimizes the risk of failure and ensures that any failures that do occur are quickly detected and resolved.
11.6. Operational
-
Performance: This refers to the speed and efficiency of the system in carrying out its functions. It involves ensuring that the system meets its performance requirements and that it can handle the expected load.
-
Reliability: This refers to the ability of the system to function without failure or downtime. It involves designing the system in a way that minimizes the risk of failure and ensures that any failures that do occur are quickly detected and resolved.
12. Design Decisions
12.1. Accepted decisions
| Architecture decision | Pros | Cons | Architecture decision record |
|---|---|---|---|
React.js |
This library is flexible, has Facebook’s and Community support, great performance and is easy to test. Intended to make Front-end development simpler. |
None of us has used this library before. |
|
TypeScript |
While JavaScript is dynamically-typed, TypeScript is a statically-typed superset of JavaScript, which means it offers strict static typing as an option but will allow dynamic typing, as well. |
None of us has used this language before. |
|
MongoDB |
A TypeScript-compatible NoSQL database that is simple to utilize and incorporate. |
MongoDB uses multi-document ACID transactions. This is one of the major limitations with MongoDB as it may lead to corruption of data. |
|
Node.js |
We will use it in SDI. Active and vibrant community, with lots of code shared via GitHub, etc. |
None of us has worked with this environment before. |
|
Express.js |
Minimal and flexible Node.js web application framework used for designing and building our web application quickly and easily. |
None of us has worked with this environment before. |
12.2. Deprecated decisions
MongoDB and API REST ADR #6 |
As we have decided not to work with public information of locations, our system is not going to need a centralized database to store information which cannot be accesed by the PODs. |
13. Quality Requirements
13.1. Quality Tree
13.2. Quality Scenarios
| Quality goal | Motivation | Usage scenarios | Priority |
|---|---|---|---|
Privacy |
User’s data must not be kept, storing just the minimum required, and retrieving the necessary from the user’s POD. |
User’s data will be stored in it’s own pod during the sign-up and usage, may it be private information relative to the user or personalized maps. |
High |
Usability |
The user won’t be able to add locations to the map if he can’t properly distinguish them in it, needing an intuitive interface clear enough to be used, be it a client or administrators. |
Almost every user of every age will be able to complete any task without previous knowledge of the website without taking long time. |
High |
Security |
The application needs to be secure enough, giving confidence enough to be used without any risk on the data being. |
The app won’t allow any third parties to access the data from the users. |
High |
Reliability |
There shouldn’t be any error that breaks the application, them being handled by the application. |
User won’t have any clear notice of any error happening while using the application. |
High |
Testability |
The application will be tested with different methods and by different users to ensure the requirements. |
The testing will help reduce to the minimum possibe every bug or bad design in the app for improving it. |
High |
Efficiency |
The system should respond as smooth and efficient as possible, as the user won’t use an application with bad performance. |
The app must use the minimum resources possible without affecting the performance to ensure a fast and fluid use. |
High |
Maintainability |
The app will go through many changes, so it is important that the code is easy to mantain and modify. |
With a good quality code, we are able to perform the minimum changes required to be modified or repaired. |
High |
14. Risks and Technical Debts
“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)
(It will obviously be extended as we find new risks and generate others technical debts as we develop the application.)
| Priority | Problem description | Considerations |
|---|---|---|
Medium |
Huge dimension of the project |
The quality and readability of the developement solutions are mandatory in order to keep order |
Medium |
Time availability of memebers of the developement team |
Good organization and distribution of the project work along the semester |
| Relevance | Technical Debts | Considerations |
|---|---|---|
Medium |
Mandatory use of SOLID |
Although it may be a great solution to the problem faced, the obligation to use this technology sets a new handicap to the start of the developement |
Medium |
Learning techincal material along the semester |
The discovery of some of the technologies of the project and some of good strategies will take place as we attend the course lectures, which coincide with the developement period |
Medium |
Performance of external resources |
The use of external resources can result in a lack of efficiency. Not only due to its functioning in general and in execution but also to the efficiency of the work performed by the team. |
Low |
The usage of TypeScript and React |
Even though the advises of our professors may conduct us to use these technologies, we are not familiar with them |
Low |
Lack of relation between members of the team |
Most probably it will not be a big deal, but the fact that we do not know each other may difficutl at least the beggining of the developement (Actualization: regarding the developement of the project, it actually was a high priority issue). |
15. Glossary
| Term | Definition |
|---|---|
TypeScript |
Free and open source high-level programming language developed and maintained by Microsoft. It is a superset of JavaScript that adds static typing. |
React |
Free and open source JavaScript library for building interfaces, maintained by Meta. |
Node.js |
Cross-platform, open source server environment, a back-end JavaScript runtime environment. |
Express.js |
Free and open source back-end framework for developing web applications and APIs with Node.js |
Solid |
Specification that lets users store their data securely in Pods |
Pods |
Decentralized and secure data stores. The pod user controls who can access the data. |
MongoDB |
Open source document-oriented NoSQL database. |
Docker |
A set of platform as a service products that use OS-level virtualization to deliver software in containers. |
CI, Continuous integration |
The practice of automating the integration process of a software so it can be done several times a day and errors are found as soon as possible. |
CD, Continuous deployment |
Extension of the CI, where code changes to the application are released automatically into the production environment. |
About arc42
arc42, the Template for documentation of software and system architecture.
By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.
Template Revision: 7.0 EN (based on asciidoc), January 2017
© We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.