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 the documentation of LoMap, an application requested from the Council of Brussels to the software development company HappySw. With this application citizens will be able to have custom maps with businesses and places of their city.

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

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 can add locations in different categories.

  • Users will be able to show the locations in a map window.

  • Users can add review scores, comments, pictures, etc. about the added places.

  • Users will be able to manage which of their information is available.

  • Users information about a place will be stored in that user’s pod.

  • Users will be able to see their friends places and information about those places.

  • Users will be able to filter their maps by category, friends, etc.

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 Description

Privacy

Each user has to be able to decide if he wants to share information.

Decentralization

As much information as possible should be stored in user’s pods.

Usability

Application must be usable by any user, whether that is a technical or non technical user.

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

Interested Companies

<Inrupt, Empathy>

See how well the students perform around the SOLID principles for their contest

Users

<Citizens>

Be able to use an easy to understand and fast aplication where they can have custom maps

Employer

<Council of Brussels>

Meet the needs of citizens, whatever those are

HappySw Owner/Professors

<Jose Emilio Labra>

Have his development team create a good application that can guarantee him good reputation

HappySw Developers/Students

<Miguel Suárez, Damián Fernández, Rubén Caño, David González>

Desarrollar la aplicacióin según la arquitectura diseñada

2. Architecture Constraints

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)

2.1. Technical Constraints

Constraint Motivation

SOLID

Used to store the personalized maps and information in personal pods that the user provides. Also, to decentralize the personal data of the users.

Map Genericity

The implementation of the maps must be generic, the main implementation is for an specific place, but you can use the application where you want.

Version Control

We will use a public repository in GitHub with different branches. The master branch is where the final application will be. In the develop branch we will have an usable application but not a finish version. All the other branches are used to individual work.

2.2. Organizational Constraints

Constraint Motivation

Time

We have some deadlines that we have to stick to. The final project must be complete before the end of April.

Size of the team

The team is made out of four people, we all have other projects and assignments so sometimes it could be difficult to meet or have a lot of time for the project.

Experience

None of us has any experience in any of the technology we are going to use.

2.3. Conventions

Constraint Motivation

Language

The language of the entire documentation will be in English.

Documentation

The documentation is going to follow the Arc32 structure.

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. <Diagram or Table> <optionally: Explanation of external domain interfaces>

Name Inputs Outputs

User

The information displayed by the webapp

Actions to customize their map, modify content and engage with friends

Pod provider

Requests to retrieve information contained in a specific pod

The requested data

Database

Query requests

The result of said requests

Map API

Request to obtain a map view in a certain location

The necessary to properly show the map

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.

<Diagram or Table> <optionally: Explanation of technical interfaces> <Mapping Input/Output to Channels>

Interface Explanation

React

Library to build the front-end user interface

NodeJS

Environment to support the backend system

Docker

Allows for deployment of the system

4. Solution Strategy

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.1. Technological Decisions

For the development of the application we have decided to use JavaScript as the main language in contrast to TypeScript. This decision is based on the ease of JavaScript and also on the experience we have with it. Although TypeScript is similar to JavaScript, we decided it’s better to stick with something we now know how to use and not try to understand another new technology. In addition to JavaScript we are going to use other technologies:

  • SOLID: Solid is perfect for the development of this application, since it allows users to maintain the user’s privacy by storing information in their personal pods

  • React.js: We chose React for its simplicity, ease of learning, and reliability (as it is a widely used library in the industry, it is highly error-tested).

4.2. Top-Level Decomposition

  • Editor: For the development of the project we decided that we are going to use Visual Studio Code, due to the ease and familiarity we have with the IDE, as well as all the extension that facilitates the development.

  • GitHub: All project progress and development is stored in a public GitHub repository. The main feature is that we all work with the same code, and we can easily share the changes we make.

4.3. Decisions to achieve quality goals

  • Privacy and Security: To guarantee the privacy and security of the data that we store or that the user wants to share, we will use SOLID technology known as PODs, which stores data and allows the user to decide what information they want to share.

  • Usability: We focus on making an interface that is user-friendly, fluid, simple and intuitive. We use some icons that are common to make some familiarity and help to understand of the application.

  • Efficiency: Although we use PODs and that can make the app slower because we need to rely on an external technology, we try to use some stored data to make the app run faster and smoother.

  • Interoperability and Scalability: We will try to make clean code that is easy to understand and modify for future updates.

  • Testability: Different test have been make to ensure that the project is running as we intended, some important test types are unit tests and usability tests.

4.4. Organizational decisions

  • Meetings: We have a meeting planned every week where we discuss what we are going to do during the week, the problems we encountered and the solutions to those or past problems. All of this can be seen on our wiki page on GitHub. Even if those are the planned meetings, we also had other meetings on Discord when some of us needed help with something or had to discuss some decisions.

  • Language: All the documentation is going to be in English.

  • Issues: The things we do and some of the decisions we make are included in GitHub issues. So if anyone wants to know what we are talking about or what things are needed, they have a place to look.

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

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

Overall view

Motivation

LoMap is an application that has a system where users can add custom places to the map. All the private data the application needs its stored in his personal POD.

Contained Building Blocks
Name Description

User

The user that interacts with the application.

LoMap

The main application that is develop to be used by the user.

Pod

Personal POD of the user where the data is stored.

5.2. Level 2

Level2 view

Motivation

We need to know how the LoMap service is built internally. As we see in the diagram we show the difference between the part of the application where the user interacts, and the part of the application that manages the data.

Contained Building Blocks
Name Description

Backend

The place where the data is managed.

WebApp

User interface of the system that the user uses to interact with the application.

Map Provider

API that provide as the map interface for the main application.

5.3. Level 3

Level3 view

Motivation

To study in more detail how the WebApp works, that is the part that user interacts with, and also the Backend, the manager of the data.

Contained Building Blocks
Name Description

Login

Page of the application where you can login.

Map

Main page where the map is display and the user can interact with.

Sidebar

Part of the main page where the data is shown.

Settings

You can change between different settings.

FriendsController

Management of the friends data.

LocationController

Management of the places data.

PodController

Management of the pod data.

RouteController

Management of the routes data.

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. User Login and Logout.

Sequence diagram login

A new user or a returning user enters the application.

6.2. Return all location of the map.

Sequence diagram return all location

A user logs into the application and the first thing the application do is load all the locations.

6.3. Add location to the map.

Sequence diagram add

A user adds a new point

6.4. Delete location of the map.

Sequence diagram delete

A user deletes an existing point

6.5. Modify location of the map.

Sequence diagram modify

A user modifies an existing point

6.6. Send friend request.

Sequence diagram send friend

A user sends a friend request.

6.7. Accept a friend request.

Sequence diagram accept a friend

A user accepts a friend request.

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

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

Infrastructure
Motivation

During the development of the application it runs on each person’s machine. However, the final product, it’s been executed on a server hosted with Netlify.

Quality and/or Performance Features

Our application depends on many different APIs, some of them are to show the map and to manage the PODs. We cannot control these APIs, so the availability and efficiency of the application may be affected. Also, these quality features could be affected by the server.

Mapping of Building Blocks to Infrastructure
Block Name Description

Netlify

Is in charge of the web access of the application

GoogleMaps

API that provides us the map where the user is going to operate the application and manage all the data.

SOLID POD

Personal and private data storage that each user has. All the private data that the user needs for the application or the data that the user generates it’s going to be stored here.

Device

Device that the user is going to use. Should need internet connection.

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

Domain model

8.2. Main architecture

The main architecture of the application is an MVC.

8.3. Privacy

One of the main goals of the entire application is the privacy of the users. For this we use SOLID technology called PODs, which stores data and the user decides the privacy of the data. Users can enter the app by login with their POD provider.

8.4. User Interface

We use the React library in combination with JavaScript for the front-part of the application. The user interface should be simple to use, have a clean appearance and be easy to navigate.

8.5. Internationalization

The application is developed to be used by many people who can use different languages, because of this the whole app can switch the language between Spanish and English.

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

Design Decision Pros Cons

React

A useful library widely used in large companies with lots of facilities and examples. It is an easy library to learn and also makes user interface development easy. It also has high compatibility with SOLID technologies.

It is the first time we use this technology, it is easy to learn to use it, but it is difficult to master it. In addition, official documentation is missing.

JavaScript

We have previous experience with this technology, and it allows us a lot of freedom in development in combination with React

The freedom it provides can also be a major drawback, as it can cause weird errors with type handling. Also, it can cause some problems when reading new code developed by other members of the group.

GoogleMaps

It is a free library that has a lot of customization and facilities for the map, we also have previous experience with it

Although it is free to use, it is limited to a time and uses, so if it is going to work for a long time, we will have to pay.

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

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.

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.

Scenario Quality Requirements Quality Scenarios

A user tries to modify other users data

Security

The data that the user storages or uses in the application must be protected and only modifiable by the user o others that the user authorized.

A user adds information that is not public and will only be available to the users he has granted permissions to access

Privacy

The user provides to others and to the application only the information the owner wants.

A new user enters the application for the first time

Usability

The application must ensure that new users know in little time how to use the basic functionality.

A user adds information in another app that follows the same data structure

Interoperability

LoMap has to be able to use the information stored by other applications as long as the data structure is the same.

New functionality is needed

Scalability

The application must be developed always thinking that this is not the final product, and we can always add new functionality.

Some functionality of the application is not running correctly

Testability

Tests will run to prevent functionality from not working as intended, even if new functionality is added.

11. Risks and Technical Debts

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

Risk Description Measure

Big Project and Time

Being a large project compared to the projects we have done so far, the magnitude and the time we have are two of the things that we need to have in mind.

Being aware of the time, deadlines and also, have a good atmosphere in the team, solve the problems we encounter and support each other during the development.

SOLID knowledge and usage

The project uses the SOLID technology, called PODs, to store the data that the user uses in the application, this is a new technology that we need to understand and use. Also, we are very susceptible to changes in the SOLID technology that can cause bugs

Read the documentation and see examples of the usage of SOLID. Trust that SOLID works properly and we have the methods to control those errors and notify them.

Usage of new technologies

As well as SOLID is something new for us, we also are using other technologies that we never used before

This can be mitigated with some experience that we will gain when developing the application, reading all the available documentation that we will need and seeing examples

11.2. Technical debts

Technical debts Brief description

Lack of experience

None of the team members have any experience in the use of technologies such as: React, Node, Solid…​ , which means that we have to make an initial effort to learn these technologies.

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

Solid

Solid is a project that aims to radically change the way Web applications work today, resulting in true data ownership as well as improved privacy.

POD

Personal data storage that is not kept in the application, is on cloud and the user decides what information the application uses.

React.js

React is an open source Javascript library designed to create user interfaces to make it easy to develop single page applications.

API(Application Program Interface)

External service that provides some functionalities that makes our development easier.

IDE

Software application that provides facilities for software development.

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.