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

LoMap is a software system being developed as a university project. It is designed to help citizens create personalized maps of places and local businesses in their city.

The aim of the project is to develop a generic software solution that can be deployed and used in other cities as well. The system will allow users to add locations in different categories like shops, bars, restaurants, sights, monuments, etc. and show them in a map window. Users will also be able to add review scores, comments, pictures, and more about the added places. The shared information will be stored in a personal pod according to the SOLID project.

The project’s initial focus is on the user, allowing them to create their personal map of the places they live. Users can manage the information that is accessible to either themselves or all of their friends. The system will allow users to see places and information about those places taken from their friends.

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

1.1. Requirements Overview

All LoMap Users will be able to:

  • ✓ Add locations in different categories like shops, bars, restaurants, sights, monuments, etc.

  • ✓ Add review scores, comments, pictures, and more about the added places.

  • ✓ See places and information about those places taken from their friends

    • Users will be able to decide, then, if their posts are shared with their friends only or remain accessible to themselves only.

In further of stages of the project:

  • ✓ Establishment owners and public entities will be able to create public map locations for their businesses

  • ✓ Users will be able to decide what city are the living in.

    • ✓ Users will be able to personalized the set of friends the locations will be shared to.

Keeping privacy in mind, all of the above, will be supported by the SOLID project specification , making use of SOLID Pods for individual data storage. This way, users will be in full control of which information they share and of who they are sharing it to.

More details are described in the following document: LoMap Assigment Description

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.

1.2. Quality Goals

Goal Description Example

Privacy

Data will only be shared with those parties the owner agrees to.

The user pins his/her own home in the map, and wants it to remain private, and not accessible to other users. It will be stored in his/her own POD, and won’t be shared with any other user nor party.

Responsiveness

LoMap will adapt it’s size and content distribution to the device it’s being accessed to, so usability is ensured.

User want’s to know the general opinion of a local restaurant of a city she’s visiting. She owns an old , small-screened phone, and so , LoMap contents will change their layout so this user can navigate successfully though it.
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

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

Product owners

José Emilio Labra Gayo, Pablo González González , Irene Cid Rico , Cristian Augusto Alonso

They’ll provide the project with architectural guidance, constraints and requirements.

Citizen Users

-

To be able to intuitively pin places, leave reviews and rate places they visit. To be able to modify or remove any of the mentioned before. To establish a network of contacts that can access their content as well as being able to access those contact’s information. To be able to revoke connections and to stop sharing information with them. To access public content posted by any other user / organization. To create several custom maps. To filter data displayed.

Business Owner Users

Representative figure (CTO, CEO..) depending on the business.

(FURTHER STAGES OF THE PROGRAM) To be able to create map locations for their business, so potential visitors and customers can access them.

Each city’s council

Representative figure (Major, secretary, governor) depending on the location.

To boost the popularity and tourism of the city , by making it easier for foreigners to discover good places. To give citizens a chance to discover new places. The application would have to complain certain specifications, for example, being secure.

HappySw FrontEnd Engineers

Juan Manuel González Sierra, Manuel Hernández Cuartas, Sebastián Radu, Batuhan Bayir, Sara Fernández Arias

They require to know the architecture in order to develop the user interface as well as to communicate it with other parts of the system. Also some constraints could take an effect on frontend decisions.

HappySw Backend Engineers

Juan Manuel González Sierra, Manuel Hernández Cuartas, Sebastián Radu, Batuhan Bayir, Sara Fernández Arias

In order to develop lower layers of the design, such as data management and business logic, these engineers will require to know all aspects of the system’s architecture.

HappySw Testing Engineers

Manuel Hernández Cuartas,Juan Manuel González Sierra, Manuel Hernández Cuartas, Sebastián Radu, Batuhan Bayir, Sara Fernández Arias

In order to test that the system is behaving as expected, engineers need to know how it is expected to work in the first place, and so, how not. For that, they’ll need to have detailed knowledge about the system’s architecture.

Existing SOLID-based applications

Other group’s members. See LoMap_enX or LoMap_esX on GitHub. Inrupt, & other pod providers.

To develop an application whose pods can communicate with other SOLID oriented applications.

2. Architecture Constraints

2.1. Technical constraints

Constraint

Explanation

Maps should be under full control of the users

One of the main focuses of the application is the user, therefore all the maps created and personalized by them should be under their full control.

Use of pods

Following with the users' focus, all the shared information by them should be stored in their corresponding personal pods according to the SOLID project, guaranteeing their real ownership of such information.

Web application

LoMap is mainly a web application, making it easy for most if not all users to use and access the application.

Generic software solution

The idea is to develop a generic solution that could be deployed in any city needed, not just an exclusive solution to one city.

GitHub

Use of a repository regarding version control.

2.2. Organizational constraints

Constraint

Explanation

Budget

The team is not getting any budget whatsoever, so if there is a need to pay for something, it will run on the members of the team.

Delivery deadlines

There are 4 deliverables every 3 weeks that should be followed accordingly before the deployment of the application.

2.3. Conventional constraints

Constraint

Explanation

ARC42

Documentation format must follow the ARC42 standards.

English

The project must be developed in such 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 where citizens can hav personalised maps about places and locals businesses in their city. The personalised maps will be under full control of the users and the shared information will be stored in a personal pod according to the SOLID project.

LoMap is a generic software solution that can be deployed and used in other cities. It is focus on the user but it also allows places to create their own space, like a digital version of their physical place.

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.

LoMap software manages information from user’s POD and displays information from places in a map. In order to do that it need a map to display and a way to access to the user’s data.

Since it is a generic software solution, it communicates with two partners to satisfy this requirements.

First we need a map provider, that is because we want LoMap to be flexible to changes so we can change the city it displays without needing a big database with all this data stored by our system. And second, a POD Manager, that will help us with authentication and data manipulation.

Business context’s diagram

Business Context diagram

External domain interfaces We will mainly use two resources for the map:

  • Google maps

  • Inrup’s Solid React library

And for managing the user’s data a React’s library that uses the Inrupt Javascript Client Libraries (Solid React SDK - solid-ui-react).

Communication partner

Inputs

Outputs

Google

geographical coordinates and a zoom level

map object

solid-ui-react (Inrupt)

podURL, session

datasets/things

3.2. Technical Context

We have decided to develop LoMap as a React Application, using express as a package manager. No Database , we will fully relly on the pods.

One of the goals is the decentralization of the application. This is done thanks to the PODs that will help us to ensure user’s privacy.

Users are the ones that own and manage the access to their information, not the application itself. To handle this, each user will be the owner of a Solid POD (Personal Online Data Store) from which the required information is extracted.

Technology

Explication

React

React is a free and open-source front-end JavaScript library for building user interfaces based on components. We use it to develop the website in frontend.

JavaScript

Is the programming language used for the development. It is one of the core technologies of the World Wide Web.

SOLID

Is used to store each users data in a POD.
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.

3.3. Technology decisions

  • Implement LoMap in mainly a React framework with a Express server. React is a really suitable framework for the use of pods and also for the developing of one page applications.

  • Javascript: The programming language we chose was Javascript as none of us had any experience with neither Javascript or Typescript and we thought the learning curve of the first one could be a bit easier to deal with.

3.4. Decisions about the top-level decomposition of the system

  • Do not have a database: During the development process we found ourselves not needing a centralised database. This is mainly because our top quality goal was privacy and to get such goal the use of the pods to store every piece of information of the user was the best approach in our eyes. It keeps the information of the user decentralised and at their disposal at all times.

  • This makes our application mainly client-side, with a server using just express.

  • No REST API needed.

3.5. Decisions on how to achieve key quality goals

  • Use Google Maps API regarding the maps of the application. Brings us a nice infrastructure regarding every location aspect of the application we could need.

  • Use the corresponding APIs in order to establish proper connection with the pods.

3.6. Relevant organizational decisions

  • Use of git workflow regarding version control. This way we can have a great amount of control over the versioning and updating of the code when developing the application.

  • Constant review and update of the projects documentation in order to develop an easy to understand application for other developers (not only potential users).

  • Delegate in the solid provider all the possible actions related to the pods, such as login, management of the adding and removing of friends or the users' own profile.

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.

4. Building Block View

Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …​) as well as their dependencies (relationships, associations, …​)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

Form

The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Hierarchy of building blocks

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

4.1. Whitebox Overall System

Here you describe the decomposition of the overall system using the following white box template. It contains

  • an overview diagram

  • a motivation for the decomposition

  • black box descriptions of the contained building blocks. For these we offer you alternatives:

    • use one table for a short and pragmatic overview of all contained building blocks and their interfaces

    • use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

  • (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

Whitebox Overall diagram

Whitebox Overall diagram

The section shows the static decomposition of the system into building blocks as well as dependencies. We are following SOLID architecture, so the system will have three main sections which communicate between them: 1. LoMap: allows users to manage personalised maps 2. Map Provider: provides the app with a map to display 3. Data Access Provider: gives access to user’s data

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name Responsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

Here you describe <black box 1> according the the following black box template:

  • Purpose/Responsibility

  • Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

  • (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

  • (Optional) directory/file location

  • (Optional) Fulfilled requirements (if you need traceability to requirements).

  • (Optional) Open issues/problems/risks

4.2. Level 2

In this view, we have a representation of the components of the system from a standpoint of the each module’s dependencies. Level 2 diagram

Level 2 diagram

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

…​describes the internal structure of building block 1.

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

Specifies the internal structure of building block x.1.

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

  • …​

All runtime scenarios where developed based on the SOLID project documentation

5.1. <Runtime Scenario 1 - User login>

  • The user logs into LoMap, by using his POD credentials.

    • Credentials will be validated by making a petition to the POD provider (INRUPT) api

      • LoMap checks the session’s Login status.

        • If the data is correct, a new session will be started, and lomap will display the user’s map.

        • In case the data is not found, user will be notified. No session will start.

UserLogin

5.2. <Runtime Scenario 2 - User adds private elements to the map>

Location Addition Deletion & Updating will work in a similar way architecture-wise. In general terms, the process will be the following :

  • Petition to the Inrupt api using the POD’s ID.

  • Inrupt api will communicate with the pod, depending on the endpoint, it will ask the pod to add, update , delete or just retrieve information.

  • In case of addition/deletion/update , LoMap will ask the POD to return the updated data (through Inrupts api)

  • Once LoMap receives the updated data, the map will be rendered again.

Below, a sequence diagram for Additions it’s provided

UserCustomizesPrivateMapPrivate

For the sake of simplicity, friend’s locations CRUD & display will be covered in an independent runtime scenario.

5.3. <Runtime Scenario 4 -Privacy levels >

LoMap will provide the users with TWO privacy levels at the moment:

  • Friends-Only posts will only be displayed to their contacts

  • Private contributions will appear to the creator only.

In further stages, a new privacy level will be implemented:

  • Public contributions to the map will be shown to any user.

The references to Friend users are stored in the Pod

  • That means that, to display friend content, a petition to the pod will be made to ask for the set of friends of a user.

    • LoMap will retrieve the locations set as friend-only by each contact from the pod and then add them to the user’s personal rendered map.

FriendsContent

6. Deployment View

Content

The deployment view describes:

  1. the technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and

  2. the mapping of (software) building blocks to that infrastructure elements.

Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.

Especially document the deployment view when your software is executed as distributed system with more then one computer, processor, server or container or when you design and construct your own hardware processors and chips.

From a software perspective it is sufficient to capture those elements of the infrastructure that are needed to show the deployment of your building blocks. Hardware architects can go beyond that and describe the infrastructure to any level of detail they need to capture.

Motivation

Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. Therefore, you need to know the infrastructure.

Form

Maybe the highest level deployment diagram is already contained in section 3.2. as technical context with your own infrastructure as ONE black box. In this section you will zoom into this black box using additional deployment diagrams:

  • UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, when your infrastructure is more complex.

  • When your (hardware) stakeholders prefer other kinds of diagrams rather than the deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

6.1. Infrastructure Level 1

Describe (usually in a combination of diagrams, tables, and text):

  • the distribution of your system to multiple locations, environments, computers, processors, .. as well as the physical connections between them

  • important justification or motivation for this deployment structure

  • Quality and/or performance features of the infrastructure

  • the mapping of software artifacts to elements of the infrastructure

For multiple environments or alternative deployments please copy that section of arc42 for all relevant environments.

<Overview Diagram>

DeploymentOverview
Motivation

In order to provide clients with a better understanding of the communication between system modules.

Quality and/or Performance Features

We’ve chosen these modules in order to keep architecture easier to maintain , and therefore to have more control over attributes as privacy , scalability..

Mapping of Building Blocks to Infrastructure
Element Description

Render

Hosting service

GitHub

Repository where LoMap’s source code is stored.

MongoDb

LoMap’s database for public information

Business Logic

Set of LoMap’s application modules.

User interface

Frontend of the application that will communicate with pod provider’s and user IO

Solid client api

Inrupt’s api LoMap will use to communicate with pods.

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

7.1. Domain model

Domain model UML Diagram

7.2. Architectural and design patterns

For this application we choose to use the Modular Monolith Architecture. The modular monolithic architecture consists of dividing our logic first into modules, and each module will be independent and isolated. Then, each module should have its own business logic. The system will only have one database. The two modules the app is using is Locations and reviews. The are being stored into the POD independently and also retrieve. Even though we have some logic to keep things stuck together since a review must have a location associated, also we must be done by a user.

7.3. Testability

We will use Unit Testing in order to assume that the development of this application goes as planed without having any functioning issues. Before implementing a new functionality we must be sure that the actual version of the application passes all our test and satisfies all our scenarios until that moment. We will test separately every part of our code.

7.4. Protection and Security

One of the main priorities of LoMap is to ensure our clients a about their privacy giving them the option to choose with who they want to share their data. The app will be secure as every user’s data will be safely saved in a POD.

Everybody using the app should trust it.

8. Design Decisions

Contents

Important, expensive, large scale or risky architecture decisions including rationals. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgement to decide whether an architectural decision should be documented here in this central section or whether you better document it locally (e.g. within the white box template of one building block).

Avoid redundancy. Refer to section 4, where you already captured the most important decisions of your architecture.

Motivation

Stakeholders of your system should be able to comprehend and retrace your decisions.

Form

Various options:

  • List or table, ordered by importance and consequences or:

  • more detailed in form of separate sections per decision

  • ADR (architecture decision record) for every important decision

8.1. Architectural Decision Record

Decision Description

Using a MERN STACK

Horizontal scalability . Good choice for real-time apps.

Using Render as a hosting service

Offers free hosting with integrated continuous deployment. Https granted too.

Having two privacy levels : Just for friends and private.

To allow the user to decide which people he/she shares the locations with.

Using Just React and Express

We will rely on solid pods, so we don’t need to provide an api + Privacy.

Folder structure

We will take advantage of the pods folders "public" & "private". Inside each one we will create the folder for the private section of lomap, and the folder for the locations shared with friends.

Usage of Azure as a hosting service

Render required organization permissions to apply continuous integration since it was a third part app. Azure is just fine for the time our app will be deployed.

8.2. Folder structure

In order to avoid collisions with other lomap applications, and so , allow our users to be able to use several LoMap solutions, we have thought of the following

POD:
    Public:
        --LoMapEn3b:
            --Pictures:
                -beach.png
            --Locations.ttl
            --Reviews.ttl
    Private:
        --LoMapEn3b:
            --Pictures:
                -Selfie.png
            --Locations.ttl
            --Reviews.ttl

8.3. Hosting service

Regarding hosting services , we’ve balanced the following options:

Hosting service Pros cons Using it would imply…​

Heroku

Used to offer free hosting

Not free hosting offered anymore

Paying - immediately rejected.

FireBase

Security.

SSL Certifcate.

Works nice with React.

Free hosting.

Serverless ( for our architecture is a con)

Since we don’t plan on going serverless , we would have to connect to the DB from the client using JS. Messy. Specially risky, since SOLID PODS require https. Other option is to go serverless.

Azure

Free credits given by university.

We used it already.

Security.

Compatibility.

Credit card info has to be provided even for free services.

Machines consume credit each minute being used, and in order to spend 0 credits we would need to delete the machines.

Being really mindful of credit left. We are not really sure if it would be compatible with continuous deployment, since that would require the service to be working. We would probably run out of credit.

Amazon Web Services

Free credits given by university.

Used it in SEW.

Security.

Compatibility.

Load Balancing & CDN

The free version is not what it used to be, now , part of the credit has to be used to take some courses aws provides , not to spend it in personal projects. So that would probably end up in credit running out.

Being really mindful of credit left. Having to make the tutorials. Just like azure, we are not really sure if it would be compatible with continuous deployment, since that would require the service to be working. We would probably run out of credit.

Netlify

Free services

300 build minutes/month

500 Websites can be hosted for free

community forum

Only one member for free

Only one person would be able to deploy and access the management UI. So each time someone of us wants to make a deploy, he/she would have to ask the person designed.

We knew no option could be perfect, specially when looking for free services. But we also knew, these options were not the best fit they could be…​At least not if we did not go serverless.

The option chosen was Azure. There, we will create a virtual machine , that will host a docker container running , made from an image of our application.

In order for it to be compatible with Inrupt, we will use port 443(https) to serve our application.

In order to enable the https certificates required , we will use certbot, letencrypt and docker volumes to map the required directories.

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

9.1. Quality Tree

The quality diagram

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.

9.2. Quality Scenarios

Quality Requirement

Scenario

Priority

Responsiveness

The application needs to have a fast response time. Any user should be able to use the features of the app with no major problems and without having noticeable delays on response times.

High

Maintainability

All of the code should be written in such a way that it can be easily modified and reused. Also, it is important that any errors or bugs can be easily fixed.LoMap will be developed minding the readability of its code and documentation.

High

Security

The user’s data will be saved and retrieved from a secured pod. We want the users to trust our application with their private data.

High

Usability

Our application will be easy to use for all types of users. It should be easy to understand and performing all the wanted actions shouldn’t raise any problems.

Medium

Privacy

The user will have the option to choose with who he wants to share his data with.

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

10. Risks and Technical Debts

Table 1. Risks

Risks

Description

Time

We don’t have a very long time to develop the application so we need to organize ourselves in such way that we can do all the things that we propose.

The team

We didn’t knew each other before this project plus two of the team members are Erasmus students so we need to speak in english with is not our main language.

The scale of the project

It is the first time some of us are working in such a project that needs the knowledge of a lot of new technologies which some of us need to learn from 0.
Table 2. Technical debts

Technical debts

Description

SOLID API

First time we hear about SOLID Pods so we have to document about them.

JavaScript

Some of the team members never used JavaScript.

React

It is a new JavaScript that all of us have to learn from 0.
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.

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

SOLID POD

Solid Personal Online Datastores, or PODs, as “where you store your data… Once stored in a Pod, you control who can access your data.”. PODs can store any kind of data from text to videos to social networking data. You can think of PODs as “containers” for data, or even “digital twins” of users

REACT

React is a free and open-source front-end JavaScript library for building user interfaces based on components.

Render

Render is a unified cloud to build and run all your apps and websites with free TLS certificates, a global CDN, DDoS protection, private networks, and auto deploys from Git.

API

API stands for Application Programming Interface. In the context of APIs, the word Application refers to any software with a distinct function. Interface can be thought of as a contract of service between two applications. This contract defines how the two communicate with each other using requests and responses.

Decentralization

Are digital applications that run on a blockchain network of computers instead of relying on a single computer.

JavaScript

Is a scripting language that enables you to create dynamically updating content, control multimedia, animate images, and pretty much everything else.

Node.js

Is an open-source, cross-platform JavaScript runtime environment and library for running web applications outside the client’s browser.

Express

Express is a node js web application framework that is used to build a single page, multipage, and hybrid web application

Stakeholder

Are all individuals or groups who have a vested interest in the performance of the business.

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.