LOMAP_EN3A

Note	This version of the template contains some help and explanations. It is used for familiarization with arc42 and the understanding of the concepts. For documentation of your own system you use better the plain version.

1. Introduction and Goals

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

underlying business goals, essential features and functional requirements for the system
quality goals for the architecture
relevant stakeholders and their expectations

LoMap is a system that brings users the possibility of creating a personalized map of their city while being in full control of their data. All the shared information will be securely stored in a personal pod.

Business will also be able to create their own space and make themselves known, as well as post images and receive reviews from their customers.

1.1. Requirements Overview

Contents

Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).

Motivation

From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.

Form

Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents.

Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.

The application must meet the following requirements:

Users will be able to add new places to their maps.
Each place may be classified in different categories.
Maps will have filters to show only certain places (e.g., those belonging to a category).
Users can interact with the places by adding reviews or comments, posting images, etc.
It will be possible to manage what information can be accessed by the rest of the users.
The information about the places will be stored in each user’s pod.
The system could store information in a centralized way as long as it respects the privacy of the users and is justified to improve performance.
Users will be able to see information about the places added by their friends.

For more information, refer to the assignment description document.

1.2. Quality Goals

Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged …

Form

A table with quality goals and concrete scenarios, ordered by priorities

Quality goal	Scenario
Privacy	User’s information must be stored in a decentralized way, ensuring they are in full control of their own data.
Robustness	Prevent user errors as much as possible and continue functioning in their presence, reacting to invalid input by giving suggestions on what to do.
Usability	The application must be easy to use, with a clear and intuitive interface.

Quality goal

Scenario

Privacy

User’s information must be stored in a decentralized way, ensuring they are in full control of their own data.

Robustness

Prevent user errors as much as possible and continue functioning in their presence, reacting to invalid input by giving suggestions on what to do.

Usability

The application must be easy to use, with a clear and intuitive interface.

1.3. Stakeholders

Contents

Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

should know the architecture
have to be convinced of the architecture
have to work with the architecture or with code
need the documentation of the architecture for their work
have to come up with decisions about the system or its development

Motivation

You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.

Form

Table with role names, person names, and their expectations with respect to the architecture and its documentation.

Role/Name	Contact	Expectations
HappySw headquarters	Inside the Company	A final product that meets their expectations. Communication with the team and feedback about the development. Quality of the code and testing. Continuous Integration and continuous delivery strategy. Comply with established deadlines and deliveries.
Council of Brussels	Product owner	A product that satisfies them, flawless and polished. All demands pleased.
Empathy.co and Inrupt	SOLID challenge organizer	As a team, we will be able to participate in the SOLID challenge. In the same way, both companies could be interested in how we use the technologies.
Teachers	Supervisors	Teachers can guide us through the process of developing the application and will mark our progress.
Citizens	Application users	A well-formed application that is useful and pleasent to use.
Development Team	Us	A well-formed application that is useful and pleasent to use.
Businesses	Application users	Specific features targeted and appealing for their business.

Role/Name

Contact

Expectations

HappySw headquarters

Inside the Company

A final product that meets their expectations. Communication with the team and feedback about the development. Quality of the code and testing. Continuous Integration and continuous delivery strategy. Comply with established deadlines and deliveries.

Council of Brussels

Product owner

A product that satisfies them, flawless and polished. All demands pleased.

Empathy.co and Inrupt

SOLID challenge organizer

As a team, we will be able to participate in the SOLID challenge. In the same way, both companies could be interested in how we use the technologies.

Teachers

Supervisors

Teachers can guide us through the process of developing the application and will mark our progress.

Citizens

Application users

A well-formed application that is useful and pleasent to use.

Development Team

A well-formed application that is useful and pleasent to use.

Businesses

Application users

Specific features targeted and appealing for their business.

2. Architecture Constraints

2.1. Technical Constraints

Constraint	Explanation
SOLID for Personal data storage	The data of each user will be stored in a personal pod, following SOLID principles.
Github	Github is required for developing the project. Team members must upload their current work to coordinate with the teammates and to record what they have done.
Continuous integration	We must be able to build and deploy the application in an automated way (including the running of every test, forcing that all of them pass to do the deployment), at least in every release. We shall make use of Docker and Github Actions for that purpose.

Constraint

Explanation

SOLID for Personal data storage

The data of each user will be stored in a personal pod, following SOLID principles.

Github

Github is required for developing the project. Team members must upload their current work to coordinate with the teammates and to record what they have done.

Continuous integration

We must be able to build and deploy the application in an automated way (including the running of every test, forcing that all of them pass to do the deployment), at least in every release. We shall make use of Docker and Github Actions for that purpose.

2.2. Organizational Constraints

Constraint	Explanation
Team size	It has been decided that the team is formed by 5 members.
Schedule	The project must be developed during the semester, with several deadlines in between.
Budget	The development team will not have any financial support, so any outlay will be on their side.
External workload	The team members have more subjects with their own workload. This is, the team must organize itself so that the semester work can be combined with the project development.
Research	We know about programming, mainly in Java, but we have not dealt with some aspects that must be developed in this project, such as application deployment or SOLID, so we must spend time to learn about them. Others are more familiar but there is still work to do to be able to handle them.
Testing	Unitary and integration tests have to be developed for the project, and we must reach a high level of code coverage.

Constraint

Explanation

Team size

It has been decided that the team is formed by 5 members.

Schedule

The project must be developed during the semester, with several deadlines in between.

Budget

The development team will not have any financial support, so any outlay will be on their side.

External workload

The team members have more subjects with their own workload. This is, the team must organize itself so that the semester work can be combined with the project development.

Research

We know about programming, mainly in Java, but we have not dealt with some aspects that must be developed in this project, such as application deployment or SOLID, so we must spend time to learn about them. Others are more familiar but there is still work to do to be able to handle them.

Testing

Unitary and integration tests have to be developed for the project, and we must reach a high level of code coverage.

2.3. Conventions

Constraint	Explanation
ARC42	The documentation must be done using an ARC42 template.
User-friendliness	This is a general-use application, so it has to be appealing and easy to use, as well as accessible to the widest range of people possible.
English	It is mandatory to develop this project in English, as we are on the bilingual program.

Constraint

Explanation

ARC42

The documentation must be done using an ARC42 template.

User-friendliness

This is a general-use application, so it has to be appealing and easy to use, as well as accessible to the widest range of people possible.

English

It is mandatory to develop this project in English, as we are on the bilingual program.

Contents

Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.

Motivation

Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.

Form

Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions)

3. System Scope and Context

Contents

System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.

If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).

Motivation

The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.

Form

Various options:

Context diagrams
Lists of communication partners and their interfaces.

3.1. Business Context

Contents

Specification of all communication partners (users, IT-systems, …) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.

Motivation

All stakeholders should understand which data are exchanged with the environment of the system.

Form

All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.

Alternatively (or additionally) you can use a table. The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.

User

Uploads pictures or writes reviews of places through the LoMap application.

PODs Provider

Facilitates the use of PODs for the system, so that users information can be stored.

Cloud Hosting System

Hosts the application so it can be accessed online.

3.2. Technical Context

Contents

Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation with I/O uses which channel.

Motivation

Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.

Form

E.g. UML deployment diagram describing channels to neighboring systems, together with a mapping table showing the relationships between channels and input/output.

4. Solution Strategy

4.1. Technology decisions

4.1.1. Framework: React

Although it is not as powerful as other options (like Angular), it is enough for developing this application and it is less difficult to learn the basics, that is, the learning curve is faster. This idea is supported by its big community, the introduction we have been given in class and the amount of projects of the course that have been developed with it and that we can take as reference.

4.1.2. Language: TypeScript/JavaScript

It is the most spread option for developing web applications in React, so we expect to find enough resources to develop our projects, in terms of information sources and libraries. Also, most of the members have worked with JavaScript in SEW, so the transition to TypeScript should be smoother.

4.1.3. Database: MongoDB

As our centralized database only stores public places, there is no relation between entities that should be taken into account, so document databases arise as a good option, as they have good performance and flexible schema. Also, given that we are working with Typescript, we can rely on MongoDB NodeJS drivers that make the task easier (such as Mongoose). In addition, we have free access to a cloud storage of 512MB, an option that many providers do not offer. Finally, it is important to mention we have used it in other subject (SDI), so the adaptation and learning process should not be a concern.

4.2. Top-level decomposition of the system

Some patterns have been discussed to tackle the design of the solution. This section is expected to be updated during the development of the application, as we will face different situations and problems where some patterns can fit in and we will reason about the best choice.

4.2.1. Architectural patterns

MVC (model-view-controller): It is very used in the development of web applications. We expect to have the view (user interface) on the client, separated from the domain logic and the persistence, which are located on the server.

4.2.2. Design patterns

Façade: Given the complexity of some subsystems and modules of the application, it could be reasonable to use a reduced interface to just focus on what we need about them, simplifying their usage.
Adapter: We assume that we will use third-party elements (libraries, etc). For this reason, we have thought about this pattern already to connect our code with them, as it is very handy in this kind of situations.

4.3. Decisions for achieving quality goals

Quality goal	Solution approach	Details
Privacy	All user data will be stored in a personal pod, so that the user has exclusive access to them, being also able to grant the access to more people.	Section 8 (Persistence), Section 9 (ADR 1)
Robustness	Validations of user input on client-side will be performed so that there is no risk of inconsistencies, security issues, etc. Server-side validations are done by means of "express-validator" on each request made to the server (check the fields have correct values) to make sure that no corrupt data is stored on the database.
Usability	Familiarity will be prioritized over innovation, so that users can rely on intuition to navigate and explore the application. In this way, several interfaces from applications that have well-proven usability (i.e. Google Maps) will be reviewed to design the user interface of the application. Aesthetics will be taken into account so it is appealing to use.	Section 8 (UI/UX)

Quality goal

Solution approach

Details

Privacy

All user data will be stored in a personal pod, so that the user has exclusive access to them, being also able to grant the access to more people.

Section 8 (Persistence), Section 9 (ADR 1)

Robustness

Validations of user input on client-side will be performed so that there is no risk of inconsistencies, security issues, etc. Server-side validations are done by means of "express-validator" on each request made to the server (check the fields have correct values) to make sure that no corrupt data is stored on the database.

Usability

Familiarity will be prioritized over innovation, so that users can rely on intuition to navigate and explore the application. In this way, several interfaces from applications that have well-proven usability (i.e. Google Maps) will be reviewed to design the user interface of the application. Aesthetics will be taken into account so it is appealing to use.

Section 8 (UI/UX)

4.4. Organizational decisions

For the development of this project, the following platforms and mechanisms have been adopted to enhance the workflow among the members of the team.

WhatsApp: A group has been created as the quickest communication mechanism to inform the other members about any update or news and organize meetings.
Teams: Platform where extra meetings (outside of the university) take place.
Github: Platform where the project is managed. We have a repository in which we develop the project. We have decided to follow what is called "Trunk-based development". This consists on having a develop branch, from which we create the branches to code. We merge them in this develop branch and, once we have everything ready, we merge develop to master. In this way, every merge to master consists on a new release (deliverable). The Github tools that we use will be presented, along with their role in the development process.
- Wiki: Here, we create a new entry to record the minute of each reunion that takes place. Each minute has a specific format, and it contains the following sections:
  - Date
  - Participants
  - State of previous tasks: It may include links to issues and/or pull requests.
  - Description of decisions taken: Sometimes they are included in the agreements section.
  - New tasks: List of the tasks that were identified and created in the meeting. It may also include links to issues created for them.
- Issues: The way to register every important event (tasks to do, problems to solve, doubts…).
- Kanban: The place where we add and update the state of issues that are related to the development.
- Pull request: We create them for every merge to develop or master, so that everyone can review what has been done and approve the changes, or reject them (being able to comment what should be fixed).

4.5. Workflow example

To complete the previous explanation, let us put an example of the steps we do to fulfill a task.

The task is defined on a meeting, so it is recorded in the corresponding minute.
An issue is created for the task. It is placed on the Kanban ("Open" state).
A branch will be created for developing it. We move the issue to "In progress" state in the Kanban.
Once it is finished, a pull request is sent for merging with the develop branch.
- If it is accepted, the process is finished, so the issue may be closed. We move the issue to the "Finished" state in the Kanban and the branch can be deleted.
- If it is rejected, the needed fixes are performed, and the pull request is updated with them. A new revision takes place.
If a bug is discovered after merging or we need to extend the functionality of that feature, a new branch may be created and the issue is reopened. Also, it is placed again on the "In progress" state of the Kanban.

Contents

A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture. These include

technology decisions
decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
decisions on how to achieve key quality goals
relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.

Motivation

These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules.

Form

Keep the explanation of these key decisions short.

Motivate what you have decided and why you decided that way, based upon your problem statement, the quality goals and key constraints. Refer to details in the following sections.

5. Building Block View

5.1. White Box Overall System

Overview Diagram

Overall View of the System

Motivation: This is an overall view of the system that describes only the most important present interfaces.
Contained Building Blocks

Block	Description
PODs	The main storage system, each user has his information stored in his own private POD.
Map API	API that allows to obtain the map to be displayed.
Data Base	Stores the minimum information required for the public map to load.
User	Represents how each individual user is set to interact with the system, through LoMap and storing his information on his POD.

Block

Description

PODs

The main storage system, each user has his information stored in his own private POD.

Map API

API that allows to obtain the map to be displayed.

Data Base

Stores the minimum information required for the public map to load.

User

Represents how each individual user is set to interact with the system, through LoMap and storing his information on his POD.

Important Interfaces: The most important interfaces, (described in the next levels) are the ones in charge of the communication with the PODs manager and the database.

5.2. LoMap Architecture

System Level 1

Purpose: Describes the architecture of the inner LoMap system, it’s how the system is structured and how each layer interacts within the system. The architecture described in the diagram System Level 1 is a Clean Architecture.
Interfaces

Interface	Description
Entities	Represent the domain of the system, those classes that describe the enterprise business rules.
Presentation	The related documents that are in charge of the presentation of the application.
Infrastructure	Those external interfaces that interact with the application, including the Database Management System, the APIs that are used (Map API), the PODs provider and any other external service.

Interface

Description

Entities

Represent the domain of the system, those classes that describe the enterprise business rules.

Presentation

The related documents that are in charge of the presentation of the application.

Infrastructure

Those external interfaces that interact with the application, including the Database Management System, the APIs that are used (Map API), the PODs provider and any other external service.

5.3. Infrastructure

White Box 1.1

Purpose: It is the Infrastructure of the application, the RestApi and the WebApp both interact with external interfaces and APIs, these interfaces are represented in this level.
Interfaces

Interface	Description
PODManager	Manages the storing of information inside the PODs provider
SessionManager	Manages the users session, is the one in charge of the login, logout,etc…
FriendsManager	Is the one that obtains the list of friends from the user, as well as their information
LeafletMapAdapter	Is the class that interacts with the Map API and presents it to the UI
PlacesController	This controller is the one in charge of adding and deleting places in the Mongo database
api	This class is the one that communicates with the RestApi, it interacts with it in order to store the places in the database

Interface

Description

PODManager

Manages the storing of information inside the PODs provider

SessionManager

Manages the users session, is the one in charge of the login, logout,etc…

FriendsManager

Is the one that obtains the list of friends from the user, as well as their information

LeafletMapAdapter

Is the class that interacts with the Map API and presents it to the UI

PlacesController

This controller is the one in charge of adding and deleting places in the Mongo database

api

This class is the one that communicates with the RestApi, it interacts with it in order to store the places in the database

Level 1: Solid adapters and repositories
Purpose: These adapters and repositories, placed under webapp/src/adapters, are meant to interact with the SOLID POD provider of the user in order to execute, the possible actions over his POD, that is to store places, reviews, comments, etc. They have been organized in this way to provide an easier access and maintainability.

5.4. Presentation

White Box 1.1

Purpose: For the presentation level of the architecture, the system is divided on several folders placed under webapp/src. These folders contain mainly components and pages, which form the base of the user interface.
Distribution

Folder	Description
adapters	Contains the classes that render an adapted version of the map
components	This class contains all the components that are used inside the pages, to represent different zones of the application.
components/basic	Some base components that serve as plain templates to represent tables, lists, etc.
components/map	The components related to either information about the map or the map itself.
components/place	The components related to information about the places
components/social	The components related to the users social state, lists of friends, groups ,etc.
pages	Located in this folder are the main pages of the application, the ones that are either on the nav menu or important to display.
styles	The css styles for all the components
styles/fonts	The text fonts for all the components
assets	Elements such as markers that are meant to be used in components.

Folder

Description

adapters

Contains the classes that render an adapted version of the map

components

This class contains all the components that are used inside the pages, to represent different zones of the application.

components/basic

Some base components that serve as plain templates to represent tables, lists, etc.

components/map

The components related to either information about the map or the map itself.

components/place

The components related to information about the places

components/social

The components related to the users social state, lists of friends, groups ,etc.

pages

Located in this folder are the main pages of the application, the ones that are either on the nav menu or important to display.

styles

The css styles for all the components

styles/fonts

The text fonts for all the components

assets

Elements such as markers that are meant to be used in components.

5.4.1. Rest API

5.4.2. Business model

Level 1

First level of the business model

api: Is the one in charge of communicating the webapp with the rest api in the server side. It is implemented with the CRUD functions although, although only the one retrieving all the public places is being used for the moment.
App: It is the main module from which the application starts. It uses directly the function for getting all the public places in the database and also the rest of modules conforming the UI.

Level 2

Second level of the business model

PODManager: Is the class in charge of doing all the interactions between the application and the PODs like getting public, private or friends places, maps, etc.
Assembler: It is in charge of transforming the objects in domain model of the web application into Things or Datasets for later storing them in PODs or viceversa.
LeafletMapAdapter: It is in charge of adapt the Leaflet api to our application in order to display the desired map with the information of places stored in PODs.

Level 3

Third level (domain model) of the business model

Placemark: Is the graphical representation of a Place. Although now it stores nothing related with the appearance, it could be in the future. However, it will always store the minimal information of a place to be display in a map as a mark. This was done because in terms of performance when showing all the public places published in the web app it is better.

6. Runtime View

Contents

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

important use cases or features: how do building blocks execute them?
interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?
operation and administration: launch, start-up, stop
error and exception scenarios

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.

Motivation

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).

Form

There are many notations for describing scenarios, e.g.

numbered list of steps (in natural language)
activity diagrams or flow charts
sequence diagrams
BPMN or EPCs (event process chains)
state machines
…

6.1. Public map generation

The placemarks of the public places are stored in a centralized database. The client is able to access this information through the API in order to generate the public map.

6.2. Change map privacy level

The privacy level of a map can be changed from the My Stuff > See details menu. The user will be able to choose between public and private read permissions, as well as to share the map with specific users.

6.3. Access to shared map

Users will be able able to have shared maps. The data of each place will be stored in the POD of its creator, while the placemarks, with references to the data locations, will be stored in the PODs of all users sharing the map.

6.4. Post comments of a place

LoMap allows users to post comments about a place from the place’s information window. This comments will be stored in the user’s POD, being possible to make them private or delete them. The url of the comment is also stored in the 'comments' dataset of the place.

6.5. See comments of a place

The comments of a place can be seen from the 'reviews' tab of the place’s information page. The application will request all the comments associated with a place and show them to the user.

7. Deployment View

Deployment view diagram

Contained Building Blocks

Element	Given use
Microsoft Azure	The cloud where the machine is created in which the deployment is done.
Server	The machine with docker containers in order to be able to execute the code of the application.
LoMap (webapp)	The code which is sent to the client and interacts with the user.
LoMap (restapi)	The code from the server side in charge of manage all the public places and communicate with the centralised database.

Element

Given use

Microsoft Azure

The cloud where the machine is created in which the deployment is done.

Server

The machine with docker containers in order to be able to execute the code of the application.

LoMap (webapp)

The code which is sent to the client and interacts with the user.

LoMap (restapi)

The code from the server side in charge of manage all the public places and communicate with the centralised database.

8. Cross-cutting Concepts

Content

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. Such concepts are often related to multiple building blocks. They can include many different topics, such as

domain models
architecture patterns or design patterns
rules for using specific technology
principal, often technical decisions of overall decisions
implementation rules

Motivation

Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. Thus, they are an important contribution to achieve inner qualities of your system.

Some of these concepts cannot be assigned to individual building blocks (e.g. security or safety). This is the place in the template that we provided for a cohesive specification of such concepts.

Form

The form can be varied:

concept papers with any kind of structure
cross-cutting model excerpts or scenarios using notations of the architecture views
sample implementations, especially for technical concepts
reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

Structure

A potential (but not mandatory) structure for this section could be:

Domain concepts
User Experience concepts (UX)
Safety and security concepts
Architecture and design patterns
"Under-the-hood"
development concepts
operational concepts

Note: it might be difficult to assign individual concepts to one specific topic on this list.

Possible topics for crosscutting concepts

8.1. POD’s structure information

|-lomap
    |-data
        |-interactions
            |-comments
            |-reviews
    	|-maps
	    |-places

This is the general structure of the folders in each user POD and each folder has different datasets.

Places: There is one folder inside for each place created, named with a unique ID and inside of them there are datasets, one for each comment, review and image about that place.
Maps: The are inside datasets one for each map created by the user. Each one have links to different places which are stored at the same time in the places folder as said before.
Interactions: It has two folders (comments and interactions) and each one has each correspondant datasets.

The permissions in order to set a place only visible for everyone, a group of people or none other than the owner himself, are managed from the application with the necessary library to change the permissions of them. That is the reason why any other extra folder to classify the places is not necessary and instead are used datasets.

8.2. UI/UX:

The application will consist of a webpage application where the user will be able to choose between a public map or different views that the user creates. This map will only show the minimal information in the form of “pins”. The user can click on the pin that a place represents, and the full information will be loaded and prompted. In this page there will be the possibility of adding photos, comments and reviews or view the ones added by other members. A friendly and familiar approach will be held when designing the different views of the application; Google Maps will be the main reference.

8.3. Persistence:

The persistence module of this development consists of the Pod’s service and our database that will store basic information from public places. The user’s system will make a call to our server to get the information that will populate the public map, then it will only call the personal pods when the information is needed (load on demand). With the same structure as for the public map, it is possible to create maps that will be stored only in the user’s pod that will be downloaded to populate that map. The user’s device will make calls to all the personal pods of its friends in the same way as for the public places. This way, we ensure that the server-side application is not going to process data that the user has only shared with his friends and, at the same time, will make that sharing possible.

8.4. Access permissions

To keep information secure, a system is needed to control access to a pod’s resources based on the user’s identity, including whether they are a friend or belong to a group of approved users. The owner of a pod has exclusive editing rights, which means that public or shared pods can only be edited by the owner. The only person who can access a pod is the owner, who can then decide whether to share it with other people or groups. The pod can be changed only by its owner or under predetermined circumstances, such as sending a review, uploading a photo, or giving a rating.

8.5. Communication and integration:

The client side of the application will be able to work independently from the server side for accessing private places, but it will not be able to access the public maps. The connection between the client and server will make it possible to display the map service, and to show the different public places of the application. That way we ensure that the service we supply does not completely rely on the rest-API. Also, the connection to pods, owned or not by the user, will allow to show private places and maps. A standard way of communicating with the pods should be established to be compatible with other “LoMap” applications. The standard has not yet been implemented; it is due to be negotiated (In our case it has not been implemented due to lack of time). The application will have to implement a module for connecting with the Solid Pods technology and other services that will be needed such as a map API or other web services.

8.6. Architecture and or design patterns:

In an earlier subject, Software design, different patterns have been set up. The usage of the corresponding adapter pattern will be used when dealing with any API needed. More patterns are described in section 4.

8.7. Rules for using specific technology:

Privacy is a main concern when developing this application. There should be a major reason for treating in the server-side private information of a user instead of on their own device. Therefore, we don’t manage private information unless is strictly necessary, such as URLs. When working with specific technologies such as Solid Pods, MongoDB or React those frameworks and technologies have their own rules that are mandatory.

8.8. Deployment:

We have chosen node.js as the runtime environment for running the server-side application. The deployment of the application will consist of a Docker container for the “web App” and another for the “rest API”. A set of actions will be configured such as unitary testing, integration tests, automatic deployment for “web App” and for “rest API”. During the process of deployment, we have faced several problems, such as the requirement of a “SSL” certificate for the Inrupt login to work or another for the API for the requests to be sent. We have used “Lets crypt” to generate the certificates, “Certbot” to enable the certificates and the free “dns” service “ClouDNS” for the domain name. The deployment is done on a virtual machine on the cloud service Azure.

9. Design Decisions

9.1. ADR 1: Private information policy.

The application development is oriented towards a more transparent and private usage of information. The application should be able to guarantee the safe treatment of the information provided to us. Solid Pods ensure that the user has control of their information all the time. Solid Servers host the Solid Pods being the information outside of our control.

Each user will have their own Solid Pod to make sure their information is secure and inaccessible to others. The information that the user provides us with will be stored inside his personal Pod. The public and private places that the user creates will be stored there.

Advantages

Disadvantages

The user will have full control of its data.

The usage of an external service like this one will generate strong dependencies with its services.

The server won’t treat private data.

The performance of the application may be affected by external factors.

The data infrastructure will be already designed.

Status: Accepted

9.2. ADR 2: Client-side computing over server-side computing.

We will try to delegate as much computation as possible to the client.

Advantages

Disadvantages

Less dependence on the server.

Less secure.

The server needs fewer resources.

Users with less powerful devices may have a worse experience.

As this is an open-source project whose code is already available on GitHub and we don’t expect to have any heavy computations, we decided that the best option was to try decoupling the application as much as possible from the server. This will allow us to have a more scalable application and a more efficient use of the server resources. In the same way, our application can run without the need of a server, but without a public map, which will allow us to have a more decentralized application.

Status: Accepted

9.3. ADR 3: Centralized database

There will be a centralized database in charge of storing the information of public places. This information will be the minimum possible to be able to generate the map (i.e., the placemarks). Any other data related to this place will be accessed through a reference to the place creator’s POD.

Advantages

Disadvantages

Decentralization of data.

Certain data redundancy in the server and the POD.

Less dependence on the server.

May lead to data inconsistency.

The server needs fewer resources.

More complex code.

Better performance when generating the map.

Public and private places are treated in the same way.

Simpler architecture of the application.

We consider that the improvement in performance along with the data decentralization are worth the possible data redundancy and inconsistency, provided there won’t be concurrent modifications of the same public place (its creator is the only one who can modify the data) and the consequences of data inconsistency between the placemark and the place do not have a significant impact on the application.

As we may have thought that in the beginning, we decided that the information is linked to the place creator’s POD, so the information is not lost or changed. The title of a place and its URL are never changed, so the information is always consistent.

Status: Accepted

9.4. ADR 4: Social places information.

The application is needed to display places that the friends of the user have shared. This friend’s information should be private and stored on their own Pod. A list of the friend’s places will be computed from the information stored on the Pods of their friends.

Advantages

Disadvantages

The user will have full control of its data.

This solution might be harder to implement.

The server won’t treat private data.

Status: Accepted

9.5. ADR 5: Uniform treatment for maps and places.

We want to promote the usage of functions that will treat the information of the places in the same way, regardless of whether they are public or private. This will allow us to have a more uniform treatment of the information and a more consistent code.

Advantages

Disadvantages

Less code will be necessary to perform the same task.

The code will be more complex.

The behavior will be more consistent.

10. Quality Requirements

Content

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

Here you can also capture quality requirements with lesser priority, which will not create high risks when they are not fully achieved.

Motivation

Since quality requirements will have a lot of influence on architectural decisions you should know for every stakeholder what is really important to them, concrete and measurable.

10.1. Quality Tree

Content

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

Motivation

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

Form

The quality tree is a high-level overview of the quality goals and requirements:

tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root
a mind map with quality categories as main branches

In any case the tree should include links to the scenarios of the following section.

Quality tree

10.2. Quality Scenarios

Contents

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

These scenarios describe what should happen when a stimulus arrives at the system.

For architects, two kinds of scenarios are important:

Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.
Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

Motivation

Scenarios make quality requirements concrete and allow to more easily measure or decide whether they are fulfilled.

Especially when you want to assess your architecture using methods like ATAM you need to describe your quality goals (from section 1.2) more precisely down to a level of scenarios that can be discussed and evaluated.

Form

Tabular or free form text.

Usage Scenarios

Usability
- System reacts to a user request to display info of a point in the map
- Standard functions, like traversing the map, should be as easy and intuitive to use as possible.
Privacy
- The private section of a user is only viewable by himself.
- Only those who are friends or belong to the same group will be able to see the information of a user that is only visible for his friends or the specified group.
Robustness
- The system will work accordingly under all specified conditions.

Change Scenarios

The API used for the map can be changed with no major modifications on the system’s modules other than the view.
Adaptation to modifications of functional requirements.
Adaptation to modifications of quality requirements.

11. Risks and Technical Debts

11.1. Risks

Risk	Description	Approach
Steep technology learning curve	We have not used Typescript, React nor SOLID before, so we could get stuck or slowed down while we learn how to use them. We might encounter additional topics to explore later in the development (for example, using Resource Development Format for representing information in the pods).	Follow the introduction and bibliography provided by the teachers, look for solutions in community forums.
Time scarcity	We can run out of time to develop all that is required in each deliverable, and provide what is asked at each deadline.	Impose intermediate checkpoints, establish a constant and maintainable development speed. Develop functional things first and build (improve) from that point on.
Coordination problems	Some people can destroy the work of others due to version control management errors, and there can be misunderstandings about the work to do and how.	Follow the indications of the teachers regarding the use of GitHub (issues, pull requests) and work in a disciplined way. Use WhatsApp and Teams to stay in contact.
First experience in a project with full responsibility on every step.	This is the first time we are involved in developing a project from scratch, from deciding architecture and design to develop a full-fledged application, and we have to reach agreements on many decisions, which can be wrong and cost us a lot of time and effort.	Apply what we know, combine with the suggestions of every member of the team and complement those ideas with what we learn in this semester (not only in this subject, but other ones). Follow the guidelines for each part of the project.
Security weak spots	The accessibility of data, and who can get it, can vary depending on the situation, and therefore there are many fronts on which information can be reached when it should not, and vice versa.	Explore the different mechanisms that SOLID provides to control and change the access to data, and study carefully every case.
Scalability issues	Due to the nature of the application, we need to have an acceptable performance with not only many users, but users with lots of data and/or that perform many accesses.	This will be studied at due time, once we start to implement the application, to approach certain aspects or refactor them in a way that the application can handle a greater workload.
Deployment issues	The deployment will require every developed test to pass, and it involves a complex configuration that may be difficult to understand.	We will try to perform a test development with enough time to fix the possible errors that may arise, taking into account that it is our first time working with Github Actions and Docker, and it is probable that the process may not go smoothly.

Risk

Description

Approach

Steep technology learning curve

We have not used Typescript, React nor SOLID before, so we could get stuck or slowed down while we learn how to use them. We might encounter additional topics to explore later in the development (for example, using Resource Development Format for representing information in the pods).

Follow the introduction and bibliography provided by the teachers, look for solutions in community forums.

Time scarcity

We can run out of time to develop all that is required in each deliverable, and provide what is asked at each deadline.

Impose intermediate checkpoints, establish a constant and maintainable development speed. Develop functional things first and build (improve) from that point on.

Coordination problems

Some people can destroy the work of others due to version control management errors, and there can be misunderstandings about the work to do and how.

Follow the indications of the teachers regarding the use of GitHub (issues, pull requests) and work in a disciplined way. Use WhatsApp and Teams to stay in contact.

First experience in a project with full responsibility on every step.

This is the first time we are involved in developing a project from scratch, from deciding architecture and design to develop a full-fledged application, and we have to reach agreements on many decisions, which can be wrong and cost us a lot of time and effort.

Apply what we know, combine with the suggestions of every member of the team and complement those ideas with what we learn in this semester (not only in this subject, but other ones). Follow the guidelines for each part of the project.

Security weak spots

The accessibility of data, and who can get it, can vary depending on the situation, and therefore there are many fronts on which information can be reached when it should not, and vice versa.

Explore the different mechanisms that SOLID provides to control and change the access to data, and study carefully every case.

Scalability issues

Due to the nature of the application, we need to have an acceptable performance with not only many users, but users with lots of data and/or that perform many accesses.

This will be studied at due time, once we start to implement the application, to approach certain aspects or refactor them in a way that the application can handle a greater workload.

Deployment issues

The deployment will require every developed test to pass, and it involves a complex configuration that may be difficult to understand.

We will try to perform a test development with enough time to fix the possible errors that may arise, taking into account that it is our first time working with Github Actions and Docker, and it is probable that the process may not go smoothly.

11.2. Technical debts

Risk	Description	Approach
Code quality	In order to deliver software that can fulfill the requirements punctually, and given our lack of experience, some aspects (like readability, homogeneity, extensibility) were sacrificed so that the delivered prototype has the required functionality. This could hinder the evolution of the application, as we head towards a complete product and many features will be added, continuing from the code that we have done so far.	Identify the code that is subject to change or will be used by other developers, and refactor it so that it is readable, maintainable and scalable. Prioritize what must be refactored regarding the available time to fulfill the next objectives.
Server code development	Given our architectural and design decisions, where the server handles the database with the public places, we have not focused in this part as the functionality that has been required thus far did not involve that. So, we have to face the implementation of the server from a very early phase, compared to a team that has taken a different approach. In conclusion, we may face more trouble than expected when working on the restapi, the database and the deployment.	Divide the tasks in such a way that the database and the restapi could be developed in parallel, so that the functionality of the centralized database can be inserted as smoothly as possible. Ideally, having the means to connect the webapp with the server with generous time margin, so that we can react to problems that could arise in the first attempts.

Risk

Description

Approach

Code quality

In order to deliver software that can fulfill the requirements punctually, and given our lack of experience, some aspects (like readability, homogeneity, extensibility) were sacrificed so that the delivered prototype has the required functionality. This could hinder the evolution of the application, as we head towards a complete product and many features will be added, continuing from the code that we have done so far.

Identify the code that is subject to change or will be used by other developers, and refactor it so that it is readable, maintainable and scalable. Prioritize what must be refactored regarding the available time to fulfill the next objectives.

Server code development

Given our architectural and design decisions, where the server handles the database with the public places, we have not focused in this part as the functionality that has been required thus far did not involve that. So, we have to face the implementation of the server from a very early phase, compared to a team that has taken a different approach. In conclusion, we may face more trouble than expected when working on the restapi, the database and the deployment.

Divide the tasks in such a way that the database and the restapi could be developed in parallel, so that the functionality of the centralized database can be inserted as smoothly as possible. Ideally, having the means to connect the webapp with the server with generous time margin, so that we can react to problems that could arise in the first attempts.

Contents

A list of identified technical risks or technical debts, ordered by priority

Motivation

“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.

Form

List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

12. Glossary

Contents

The most important domain and technical terms that your stakeholders use when discussing the system.

You can also see the glossary as source for translations if you work in multi-language teams.

Motivation

You should clearly define your terms, so that all stakeholders

have an identical understanding of these terms
do not use synonyms and homonyms

Form

A table with columns <Term> and <Definition>.

Potentially more columns in case you need translations.

Term	Definition
UX User Experience	How a user interacts with and experiences a product, system or service. It includes a person’s perceptions of utility, ease of use, and efficiency. Source: Wikipedia (User experience).
UI User Interface	The space where interactions between humans and machines occur. The goal of this interaction is to allow effective operation and control of the machine from the human end, while the machine simultaneously feeds back information that aids the operators' decision-making process. Source: Wikipedia (User Interface).
TypeScript	Developed by Microsoft, it is a superset of JavaScript that adds static type checking and classes. These features make it widely used nowadays for web applications development.
React	An open-source JavaScript library for developing user interfaces. It can be used to develop web applications, and it has to be complemented with other libraries to develop full-fledged products.
Node.js	Open-source, event-oriented runtime environment for JavaScript in servers.
MongoDB	Open-source NoSQL database system that stores data in documents.
Mongoose	Node.js library that allows to work with MongoDB databases while providing useful features like validation, type casting and query building.
JavaScript	A programming language that allows the integration of sophisticated functionality on web pages. Together with HTML and CSS, it is one of the core technologies of the World Wide Web. It can update, manipulate, and validate data as well as update and edit both HTML and CSS.
GitHub	Is an Internet hosting service for Git-based version control and software development. Git collaboration is made simpler for both individuals and teams to use. Additionally, it offers wikis, task management, bug tracking, and access control for each project.
SOLID	Created by Tim Berners-Lee, it is a specification that aims at decentralizing the users data, by employing containers called Pods. The main idea is that the user is the owner of the data, having the power of managing the access to the personal data.
Project (SOLID)	Aims to create interoperable ecosystems of services and data where users are free to openly use their data across various services and applications. Solid IDs, Solid Pods, and Solid Applications are its three foundational pillars.
ID (SOLID)	A unique identifier that you use to access your data and log into Solid applications.
Pod (SOLID)	A personal internet datastore where you can save your information. Who has access to your Pod and what they can do with your data are both things you can manage.
Application (SOLID)	Any online application that reads or writes data from your Pod using Solid technology.
Pin	A mark that designates a specific location on the map. It can be used to communicate information, represent locations and obtain directions. For instance, Google Maps utilizes a shadowed red teardrop-shaped pin.
ADR	Architectural Decision Record. A documentation of a software design decision that satisfies an architecturally significant functional or non-functional requirement.
Docker	A platform that uses OS-level virtualization to deliver software in packages called containers. It is used to deploy applications inside software containers, where they can run in isolation from the operating system.
WebApp	A web application that is stored on a remote server and delivered through the Internet browser. In our case, we refer to the part of the application that will run on the client side.
RestAPI	A software architecture style that we used for providing a set of functions to access the data of the application. In our case, we refer to the part of the application that will run on the server side.

Term

Definition

UX User Experience

How a user interacts with and experiences a product, system or service. It includes a person’s perceptions of utility, ease of use, and efficiency. Source: Wikipedia (User experience).

UI User Interface

The space where interactions between humans and machines occur. The goal of this interaction is to allow effective operation and control of the machine from the human end, while the machine simultaneously feeds back information that aids the operators' decision-making process. Source: Wikipedia (User Interface).

TypeScript

Developed by Microsoft, it is a superset of JavaScript that adds static type checking and classes. These features make it widely used nowadays for web applications development.

React

An open-source JavaScript library for developing user interfaces. It can be used to develop web applications, and it has to be complemented with other libraries to develop full-fledged products.

Node.js

Open-source, event-oriented runtime environment for JavaScript in servers.

MongoDB

Open-source NoSQL database system that stores data in documents.

Mongoose

Node.js library that allows to work with MongoDB databases while providing useful features like validation, type casting and query building.

JavaScript

A programming language that allows the integration of sophisticated functionality on web pages. Together with HTML and CSS, it is one of the core technologies of the World Wide Web. It can update, manipulate, and validate data as well as update and edit both HTML and CSS.

GitHub

Is an Internet hosting service for Git-based version control and software development. Git collaboration is made simpler for both individuals and teams to use. Additionally, it offers wikis, task management, bug tracking, and access control for each project.

SOLID

Created by Tim Berners-Lee, it is a specification that aims at decentralizing the users data, by employing containers called Pods. The main idea is that the user is the owner of the data, having the power of managing the access to the personal data.

Project (SOLID)

Aims to create interoperable ecosystems of services and data where users are free to openly use their data across various services and applications. Solid IDs, Solid Pods, and Solid Applications are its three foundational pillars.

ID (SOLID)

A unique identifier that you use to access your data and log into Solid applications.

Pod (SOLID)

A personal internet datastore where you can save your information. Who has access to your Pod and what they can do with your data are both things you can manage.

Application (SOLID)

Any online application that reads or writes data from your Pod using Solid technology.

A mark that designates a specific location on the map. It can be used to communicate information, represent locations and obtain directions. For instance, Google Maps utilizes a shadowed red teardrop-shaped pin.

ADR

Architectural Decision Record. A documentation of a software design decision that satisfies an architecturally significant functional or non-functional requirement.

Docker

A platform that uses OS-level virtualization to deliver software in packages called containers. It is used to deploy applications inside software containers, where they can run in isolation from the operating system.

WebApp

A web application that is stored on a remote server and delivered through the Internet browser. In our case, we refer to the part of the application that will run on the client side.

RestAPI

A software architecture style that we used for providing a set of functions to access the data of the application. In our case, we refer to the part of the application that will run on the server side.

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