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

This is a mock to test how to deploy the documentation.

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 intends to be an easy-to-use tool for people to create, customize, and share personal maps filling them with the places they live.

This map application allows the user to create multiple different maps that are empty.

The user then will create locations or photos for the places they want and add them to any of their own maps. You can add friends or groups and share these location with them so that they show on their maps for them to comment or give a score

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.

  • Users must be able to create different maps. One user could have more than one map

  • Users must be able to add locations to their own maps. Initially shops, bars, restaurants, sight and monuments.

  • Users must be able to add reviews to locations. Scores, comments and pictures could be added to a location.

  • Locations could be shared with other users, a friend or a group of friends.

  • User’s data will be extracted and stored into SOLID PODS. Users' locations information will also be stored in the user' POD.

  • Locations will be printed in a map. It will have filters. Initially category, friends, and different types of locations.

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

Priority Description Expectations

1

Privacy

Users' data will only be accessed when permissions have been granted.

2

Decentralization

Users' data will be accessed and stored using Solid PODS.

3

Usability

The application must be intuitive so a novice user should be able to navigate in less than 10 minutes.

4

Accesibility

The web application will comply with WCAG 2.0 at level AAA.

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 Description Expectations

Developers

Mario Pérez Fernández (uo283720@uniovi.es)
Ivan Vega Gracía (uo276670@uniovi.es)
Silvia Suárez Prendes (uo277412@uniovi.es)
Sara María Ramírez Pérez (uo276188@uniovi.es)
Elías Llera García-Riaño (uo271407@uniovi.es)
Andrés Álvarez Murillo (uo278249@uniovi.es)

Group of students in charge of developing the project.

Deliver a fucntional version that meets the specified requirements.

Teachers

Pablo González González (gonzalezgpablo@uniovi.es)
José Emilio Labra Gayo (labra@uniovi.es)

Professors of the course in charge of supervising and guide the development team.

Evaluate the final delivery and help through the process.

Users

Final users of LoMap.

Use the application, and they should be satisfied by it.

Solid

https://forum.solidproject.org

Specification to store users' data in a decentralized manner.

Gain decentralization of data.

Compaines

Inrupt
Empathy

Compaines involved in the Solid challenge.

Evaluate the projects and decide a winner for the challenge

2. Architecture Constraints

2.1. Technical constraints

Use of SOLID PODs

The user’s information must be secured and stored in personal SOLID pods.

Use of Git

The version control of the project must be done using Git.

2.2. Organizational constraints

Fixed number of members

The Development Team has a fixed number of members. In case there is a loss of staff, we must take over their part of the work.

Weekly meetings

There must be a weekly meeting in which we will verify a minute where we can discuss the work distribution, problems, …

Communication and code sharing in GitHub

All members of the work must use GitHub to communicate, organize the work, write the minutes, …

Milestones

During the course of the project there will be four deliverables in which several requirements must be met.

2.3. Conventional constraints

Documentation in Arc42

The documentation of the project must follow the Arc42 template for documentation and communication of software and system architectures.

Use of the English language

The project and the documentation must be written in the English language.

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

LoMap is a software system designed to provide users with personalized maps about places and local businesses in their city. The maps will be under the full control of the users and the shared information will be stored in personal pod according to the SOLID project.

Another feature of the application will be to allow places to create their own space, like a digital version of their physical place.

3.1. Business Context

Bussiness context diagram

The system will allow users to add locations in different categories, see places and information about those places taken from their friends, show the locations in a map window, add review scores, comments…​

The user is able to add locations in different categories, add review scores, comments, or pictures about the added places. It also will be possible to manage from the application the information that is accessible with other users and friendships.

The system is structured in two parts: a frontend and a backend. The user only interfaces with the frontend, which in turn interfaces with the backend, which then works with the Solid Pod provider and the database serve the data the frontend might need. The credentials of the users are stored in the PODs and the maps service provides the application with a visual map to show it to the user.

3.2. Technical Context

Technical context diagram

The frontend of the application is made with React, Redux and has a Map API wich provides the application with visual maps. The frontend will communicate with the Solid POD by means of a library that is not determined yet.

The Map will be used to search for an API and it will make HTTPS requests. It will also communicate with the backend of the application using a technology that is not determined yet.

The user will access the frontend of the application by using different devices such as a PC or a smartphone.

4. Solution Strategy

4.1. Technology decisions

These are the technologies that we have decided to use, some of them may vary in future iterations of the project:

  • SOLID PODs for security

  • TypeScript as programming language

  • MongoDb as our cache DMBS

  • Redux using React as UI

  • Chakra UI (for the implementation of the views)

4.2. Design decisions:

The general design decisions.

  • Project has two main parts, connected using a facade:

    • Webapp (frontend): It has different views, it communicates with the user with different views, and with the backend using redux hooks

    • RestAPI (backend): controls the access to the data. This data can be stored in the user’s POD or in our database

  • The application will have two sessions, one for the webApp and another one for the restAPI.

    • The webAPP session will be used to link the webAPP with the restAPI.

    • The restAPI session will be created after authenticating with the corresponding solid provider. It will contain the authenticated fetch for private resources in the pod.

Session structure

  • Use of a local database to cache shared resources and improve performance.

Mongo schema

  • Resources stored in the POD will be RDF resources and will follow as close as possible the schema.org specification.

Pod schema

  • Friendships will work without a friendships invite system. When a user adds a friend, it is allowing that friend to see his/her shared resources, and asking the application to fetch the other user’s resources. If the other user also adds the first one as a friend, he/she will be able to see the resources, but they will not be retrieved if one of them dos not.

4.3. Organizational decisions

  • All developments will be recorded in an issue and added to the kanban board of the project, where its state will be updated periodically.

  • All developments will be done in a personal branch forked from the "develop" branch. When the functionality is finished, it will be merged to the "develop" branch with a pull-request.

  • When the "develop" branch reaches a stable point, it will be merged to the "master" branch.

  • Documentation changes will not be done in the "develop" branch, but in the "documentation" branch, following the same strategy.

4.4. Quality decisions

The main quality attributes that we will focus on are the following:

Quality goal Scenario Solution approach

Privacy

Any user using our application will feel their data is secure

We will use SOLID Pods to ensure that user’s data is not compromised.

Usability

All users, regardless of their level, are able to navigate and use the application correctly

We will use UX conventions to ensure that the app has its components presented in a familiar way

Accessibility

All users, regardless of their physical and mental capabilities should be able to use the application.

We are going to use external accessibility tools.

5. Building Block View

The LoMap application is mainly divided into two modules with very differentiated behaviour: the WebAPP and the RestAPI. Each of the modules has several components, focused in smaller functionalities.

5.1. Black box view

5.1.1. Level 1

The LoMap application is divided into two modules, each of which interact with different external services.

Building block level 1

WebApp

The web app is the module responsible for managing the communication with the user. It will manage the GUI by means of different views, some of which access an external API to implement the map Leaflet. It communicates with the Rest API (described later on) with http requests. On login, it redirects the user to its POD provider to handle the login process, but doesn’t access the POD’s data

RestAPI

The rest API will manage the business logic and access the data of the application. The data will be stored in the user’s POD for maintaining the data secured. Some other non-sensitive data will be stored in the database for better performance

It will receive the petitions of the web app (described before), process them, access the necessary information and return a response in form of data.

5.1.2. Level 2

Each of the previously mentioned modules is divided into smaller components, whose behaviour is described in this section.

Building block level 2

Views

Component responsible for rendering the GUI.

Solid access

Component in charge of accessing the user solid POD. The POD accessing logic is completly transparent for the WebAPP, only the RestAPI has to manage that connection.

Facade

Component in charge of receiving the petitions and manage them. Responsible for the business logic.

DB access

Component in charge of accessing the database. Reads, stores, updates and deletes information.

5.1.3. Level 3

Let´s now have a closer look at both the WebAPP and RestAPI individually, showing the information flow and the communication between the different modules.

WebAPP

Here we can see that the WebAPP actually has a middle component between the views and the RestAPI access components, responsible for cache information in the client in order to improve performance.

Building block level 3

RestAPI

Here is a more detailed explanation of the RestAPI structure. We can see that the facade is implemented in a module with several routers. Those routers access the services, which apart from accessing the Solid POD, are in charge of data validation and transformation. Those services are also in charge of managing the database access.

Building block level 3

6. Runtime View

6.1. User Login

  • The user wants to log in with their POD to access the webapp.

    • The user will be able to fill a form that will redirect him to its POD’s provider in order to give the application access to its POD’s information or deny it.

    • The structure of the login is not as simple as a typical login flow, since it is not managed by our application but by the users Solid POD provider. The information flow works as follows.

Flow of information when a user logs in

6.2. Adding a Location

  • The user wants to add the location restaurant to the webapp and see it on the map.

    • The user will click on a place on the map and a form will be displayed where the user will be able to select a location category and the name for the location to be placed and seen on their map and it will be saved on their POD.

6.3. Reviewing information about a place

  • The user wants to select a friend’s added location and see the pictures they added to it.

    • Locations made public or shared with the user will be able to be accessed by the user to review additional information that the creator added to the place.

    • When accessing any shared resource (not only shared locations, but reviews as well), the information flow does not go through only the user´s pod, but through our database as well. This database´s intention is not to manage the user´s data (the "master" data is always the one stored in the pod), but improve performance by reducing the calls to external places.

Flow of information when adding and accessing any shared resource

6.4. Changing privacy settings (Not implemented yet)

  • The user doesn’t want their friends seeing the locations she added to the map so they acess the settings of the webapp to disable sharing them.

    • The different settings about what information on the places and the user is accesible by their friends will be able to be changed, giving different options for each parameter.

6.5. Adding a new friend

  • A user navigating the app wants to search and add a concrete friend to their friend list.

    • The user will be able to write the WebId of a friend’s POD and also a NickName just to be similar to an agenda.

6.6. Deleting a friend (Not implemented yet)

  • A user wants to remove a friend from their friend list.

    • The user will be given the option to remove a friend from their list, if they do the system wont consider them a friend and all places shared with them will no longer be shared.

6.7. Creating a friend group (Not implemented yet)

  • The user wants to create a group of friends and manage privacy on the group.

    • The group of friends will be treated as a single friend, after creation it will be stored on the database and the information that is shared or not will affect the whole group.

7. Deployment View

7.1. General Diagram

deployment general diagram

7.2. Infrastructure Level 1

deployment l1 diagram
Motivation

The deployment with Docker environment with two containers, a React app served by Nginx and a NodeJS API with Express, is driven by the need to create a robust, scalable, and easily deployable system. The main motivation behind this deployment view is to ensure that the system can be deployed and managed with ease, and that it can deliver a high level of performance, reliability, and availability.

Quality and/or Performance Features

  • Low cost.

  • Simple deployment with docker registry.

  • Scalability → NGINX can be easily scaled horizontally by adding more servers, making it ideal for serving large apps with many users.

  • System compatibility → The React app and NodeJS API are kept separate from the underlying infrastructure.

  • Load balancing: NGINX can distribute traffic across multiple servers, helping to improve performance and ensure high availability. Can be used with auto-scaling.

  • Disk space saving thanks to the elimination of files related to the virtualized O.S.

  • Configuration is centralized on "nginx.conf" file.

  • Share libraries with the other containers → Lower disk usage.

  • Ability to operate with thousands of simultaneous connections.

Mapping of Building Blocks to Infrastructure

  • The "Lomap" block would correspond to the environment that Docker creates

  • The "WebApp" block corresponds to the Static Provider Container, which provisions the React application "WebApp"

  • The "Rest Api" block corresponds to the NodeJs Container, which provisions the Express application "RestApi"

7.3. Infrastructure Level 2

7.3.1. StaticProviderContainer

deployment nginx diagram
Motivation

NGINX is a web server that provides a high-performance, scalable platform for delivering web content. It is ideal for serving React apps because of its ability to handle large amounts of traffic, efficiently serve static content, and provide robust security features.

Quality and/or Performance Features

  • High-performance → NGINX is designed to handle high traffic loads and can efficiently serve large files, which is important when serving a React app that may have many components and dependencies.

  • Caching → NGINX can cache static content, which can improve performance and reduce the load on the backend servers.

  • Security → NGINX provides a range of security features, including SSL/TLS encryption, access control, and DDoS protection.

  • Easy Configuration → Nginx has a simple configuration syntax, which makes it easy to set up and configure for serving a React app. This can save time and reduce the risk of errors or misconfigurations

Mapping of Building Blocks to Infrastructure

The "WebApp" block corresponds to the Static Provider Container, which provisions the React application "WebApp"

7.3.2. NodeJsContainer

deployment node diagram
Motivation

When using NodeJS to serve an ExpressJS API, you can take advantage of the asynchronous, non-blocking I/O model of NodeJS. This means that your API can handle a large number of requests concurrently without blocking other requests. This can lead to faster response times and better performance compared to traditional server-side languages like PHP or Java.

Quality and/or Performance Features

  • Lightweight and Fast → ExpressJS is a lightweight framework and provides a minimalist and fast development environment for building APIs. It doesn’t include features that you won’t use and provides only the required functionality.

  • Flexible and Scalable → ExpressJS is highly flexible and allows developers to customize their API development environment. You can add or remove components easily, making it highly scalable for your business.

  • Easy to Learn → ExpressJS is one of the easiest frameworks to learn and implement, even for beginners. It provides well-documented documentation, and the community support is vast.

  • Modular Architecture → ExpressJS follows a modular architecture that allows developers to add third-party libraries to extend its functionality.

  • Provides middleware → ExpressJS has built-in middleware that enables developers to process requests, validate data, authenticate, and more.

  • Efficient Routing → With the use of ExpressJS, developers can easily manage routes for their API endpoints, making it easier to understand and debug issues.

  • Easy Testing → ExpressJS provides an environment that is easy to test, making it easy for developers to run tests without incurring extra costs.

  • Works well with NodeJS → As a framework built on top of NodeJS, ExpressJS is highly compatible and provides an efficient environment for building APIs.

Mapping of Building Blocks to Infrastructure

The "Rest Api" block corresponds to the NodeJs Container, which provisions the Express application "RestApi"

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

Security is extremely important as only authenticated users using a POD must be able to access the map view as well as the other functionalities. All routes are protected, so they are not accessed without this authentication. The backend is also protected from unauthorized requests.

8.2. Privacy

Privacy is extremely important as data from the user’s locations and friends must not be seen or stored outside the PODS. In order to maintain this the RestAPI manages the communication with the frontend saving only the nicknames of the users on a database and all sensitive information on the PODs.

9. Design Decisions

9.1. Technologies

Typescript
Reason

Typescript and JavaScript were the two main options for the language of the system. Because of the number of resources available to implement a React application with Typescript, we decided to choose it over Javascript.

Pros

  • Good integration with the technology stack.

  • Good option for web applications.

Cons

  • No member of the team is familiar with it.

React
Reason

React is one of the most used if not the number one option to develop the front-end of web applications. We decided to choose it over Angular due to the number of already implemented components available.

Pros

  • Lots of resources to learn.

  • Many libraries.

Cons

  • Managing states can be troublesome.

Redux
Reason

Redux is a pattern that facilitates state management. Since we consider this a con of React, we think it can be a good way of solving it.

Pros

  • Easy debugging and testing.

  • Predictability.

Cons

  • If we end up not using several data sources, it could add overhead for no real reason.

Node EXPRESS
Reason

Since we decided to use Typescript and React-Redux, using Node is mandatory and the sample project uses EXPRESS, we decided using for the final application as well to make configuration easier.

MongoDB
Reason

The alternative was using a MySQL server, but since the integration with a Node application is much more complicated and the newer versions of Mongo have relational operations, we decided to choose the second option.

Pros

  • Scalability

  • Decentralization of the application

  • Flexibility

Cons

  • Although relational operations are available, they are not as optimized as in a traditional database.

Chakra UI
Reason

The weight of the package was optimal and it is intuitive.

Pros

  • It has a great variety of components and they are very useful.

  • Accessibility.

  • Easy-to-understand documentation.

Cons

  • It is not possible to style some of the components it provides.

  • We have not found many examples of using the component templates it offers.

Inrupt solid libraries
Reason

Managing the pods with ease

Pros

  • Greatly reduces the necessary code to do basic operation with tho user’s pod.

Cons

  • We have an extra dependency that could be avoided.

  • Some basic functionality that we need is not implemented in the library.

9.2. Architecture

SOLID pods connection to the RestAPI
Reason

The application will be divided into two big modules: WebApp (front-end) and API (back-end). We have the option of connecting the SOLID pods to any of the two modules. Our decision is to connect it to the RestAPI.

Pros

  • Business logic isolation in the WebAPP.

Cons

  • Not many examples of SOLID Pod access from the server side.

Local database used as cache
Reason

After developing the first prototype of our application, we realised that around 80% of the response time of the server was due to the delay in retrieving data from the user´s Pod. In order to improve performance, we decided to store all the information in the user´s pod and keep it as the "master" information, but to store a copy in a local database and use it when accessing shared resources (information from other users' pods).

Pros

  • Improved performance.

  • Data redundancy.

  • The user privacy is not affected, only data that the user wants to share is stored.

Cons

  • Only improves performance when accessing other users´ data.

  • Adds complexity to the RestAPI. image:

Location filters in the WebAPP
Reason

In order to reduce the number of calls to the RestAPI and consequently the number of calls to external sites (Pod Providers), the filters will be executed in the WebAPP cache (store module).

Pros

  • Reduced response time when applying filters.

Cons

  • Implementation of some business logic in the WebAPP.

10. Quality Requirements

10.1. Quality Tree

Quality tree diagram

10.2. Quality Scenarios

Quality goal Scenario Approach Priority

Accessibility

Users want to be able to traverse the application easily.

-

High

Privacy

We need to protect the user’s data. The application will only take essential data from users and it will be done in a decentralized way.

User’s data will be retrieved from the user’s POD.

High

Security

Our application will be developed in such a way that the user’s data will be stored in a secure place. If the user doesn’t trust our site, they won’t use it.

User data wont be accessible for any third parties and it will be stored in a secure system.

High

Usability

The user wants the application to be as intuitive as possible, and the maps to be easy to understand and navigate through.

-

High

Decentralization

Decentralization of the log in process (serverless).

It is achieved by means of calling the POD provider and delegating the process to it.

High

11. Risks and Technical Debts

Risks/Technical debt Description

Delivery time

We are limited by the deadline of the course and also by the time we’ll spend working on the other courses.

Knowledge of SOLID

It’s our first time using this technology so we have no idea of how to work with it. We will spend some time researching and practising.

GitHub

Some of the team members are facing pull request and branches for the first time, so it will take time to be confortable using GitHub for the team.

Lack of knowledge of some technologies

We have no experience working with React or Typescript.

Big project and big team

We are 6 people working on that project, so communication will be crucial. We must help and collaborate with everyone in order to have good developer experience among this project.

Database dependency

Right now, there is no functionality developed to restore the shared resources of users. If the database gets corrupted or the data is lost, a script to reload every shared resource will need to be implemented

Lack of component modularity in webAPP

Right now most components in the WebAPP are not well differentiated. Upgrading or extending their functionality could be more complex than it should.

Pod Provider dependency

Although we do have data redundancy with the cache database, we still depend on the provider in order to do the login or access the "master" data of the users.

12. Glossary

Term Definition

WCAG

Web Content Accessibility Guidelines (https://www.w3.org/WAI/WCAG2AAA-Conformance)

PODS

Pods are like secure personal web servers for data. When data is stored in someone’s Pod, they control which people and applications can access it. (https://solidproject.org)

Container

Lightweight, standalone, and executable package of software that contains everything needed to run an application, including code, system tools, libraries, and settings.

DDoS protection

Set of technologies, practices, and strategies that organizations implement to prevent, mitigate, or minimize the impact of Distributed Denial of Service (DDoS) attacks

Framework

Standardized set of libraries, tools, and conventions that provide a foundation for developing software applications

Component

Modular, reusable, and independently deployable part of a software system that performs a specific function or set of functions

Module

Self-contained, interchangeable part of a software system that performs a specific function

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.