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

DeDe is a online shop project for the course of Software Architecture, University of Oviedo. We are the developers from team 3A, from the English group:

  • Pelayo González García

  • Martín Beltrán Díaz

  • Pablo García Fernández

  • Carlos Garriga Suárez

  • Josué Fernández Argüelles

  • Enzo Barbón Lema

DeDe (Decentralized Delivery) is an online shop developed following the SOLID project approach, allowing the users to store their personal information in decentralized and secure data storages, the so-called PODs. The shop itself won’t store any personal data from the users, but will ask them to provide a POD with their address, in order to send the purchased goods. If you want to know more about the solid project, do not hesitate to visit the SOLID project site.

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

The system will emulate an online shopping system where end-users can select and order products to buy. According to the distance between the distribution center and user’s address, the shop will calculate the total cost of the purchase and the delivery, and once the user pays, the order will be recorded and the delivery will be simulated.

The app will record each transaction and order, so a user can review orders done.

Needless to say, every time the app needs user’s location, the user should provide a POD, as our service does not store any shopper’s personal information.

1.1.1. Technical Deployment

DeDe will be implemented using TypeScript with React framework, and data will be stored in a Firebase database. The web service and deployment will also be provided by Firebase, since it provides 300$ bonus for students and a set of diagnosis tools to test loads and web performance.


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


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.


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

The top three quality goals for the architecture whose fulfillment is of the highest importance to the major stakeholders.

Quality Motivation


DeDe should look after users privacy, not allowing them to store private data for deliveries (apart from the address), such as phone number, the receiver of the package, time laps when you can pick it up…​


Data such as account passwords or previous orders should be stored and only be accessible for the proper user. The database should also be protected against SQLInjections, and passwords must be encrypted.


As an online shop, DeDe doesn’t have an opening and closing time, so it must be working 24/7.


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.


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 …


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

1.3. Stakeholders


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


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.


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

Role/Name Contact Expectations


Martin Beltran, Josue Fernandez, Pablo Garcia, Pelayo Gonzalez, Carlos Garriga and Enzo Barbón.

People in charge of developing the app. They expect to improve their software architecture knowledge and their designing and coding skills.

Professors & Reviewers

José Emilio Labra Gallo, Pablo González González

They will guide the developers throughout developing process, providing tutorship and help when needed.


People interested in buying products and good from our online shop.

Previous year’s students

Previous year’s projects may show the developers what an actual documentation and project development looks like, so they can find inspiration in those projects.


People that are inolved in Inrupt will have access to our project that is public in Github


2. Architecture Constraints

The constraints will be divided into business and technical.

2.1. Technical Constraints

These constraints will limit the team’s ability to change the technology environment.

Constraint Explanation


TypeScript is the programming language in which the project has to be implemented.


The application must be implemented using the React Framework.


The project must be constantly updated in GitHub, showing all the members collaborations.


The documentation must follow the Arc42 templates.


The project will user SOLID user pods as data retrieval.

Continuous integration system

The application will be deployed using a continuous integration system.

2.2. Organizational Constraints

Constraint Explanation


The project must be done in 11 weeks.


The team is composed of 6 members.


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.


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.


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

3.1. Business Context

Entity Inputs Outputs


The user’s input will be the interface provided by the webapp

The outputs may be the POD generated by the user and also the information that will be received by the app


The POD will store the users data in order to follow the SOLID project

It will provide the information needed by the webapp


The user will be able to make orders and also to access the information about their orders done

The information that provides to the user logged


The POD will have most of the information so we will not store it, but we will store other stuff like the products to buy

Obviously the database will be linked to the web

Business Context

3.2. Technical Context

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

What is a POD? In SOLID architecture we can define a POD as a Personal Online Data Store. The user can have there any information he/she wants and can be hosted anywhere.

The application will be written in Typescript with React, being Typescript a language similar to Javascript but with types and React a framework to facilitate the creation of user interfaces.

Technical Interface Description


Architecture followed in the project in the use of data


Language used to build the application


Library to help the building of the user interfaces

4. Solution Strategy


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.


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


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

The technologies we have decided to use for the development of the app are:

Solid Community, Inrupt and SolidWeb → Main POD server providers. Widely used. The app works with all the PODs that follows the same standard as them.

Firebase → Serverless service for the deployment and development of the application, providing the web and DB hosting, a prepared backend for the DB and a way of deploying isolated custom functions. It also provides authentication storage, so user’s email and password (hashed) are safe and secure.

React and TypeScript have not been included in the list since it is compulsory to use them, and are not "a decision" itself.

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

MVC → Probably the most common architectural pattern. It is used to decouple the interface, from the data and the domain logic.

4.3. Decisions on how to achieve key quality goals

Privacy → To achieve privacy, we won’t store any personal data from our users apart from their past orders.

Security → As users need to log in in the application, we will store their user’s passwords encrypted. Also, we plan to protect avery form field against SQL Injections by means of prepared statements.

Availability → Using an external reliable web-hosting service we ensure that the web and the database will be available almost 24/7.

4.4. Organizational decisions

To enable communication within the team members we have created a Discord Server for meetings and a Whatsapp chat group in order to schedule those meetings. We have refined tasks in a GitHub project, so we can follow the overall work and keep a backlog of the remaining tasks.

We also have an Issue system and a wiki, working as a log for decisions and minutes for meetings.

5. Building Block View


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.


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.


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

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

Whitebox Overall System


The building block view is meant to be as a quick overview of our application by making it’s structure easily understandable throught abstraction.

Contained Building Blocks

Scope & Context:


A client using our application.


The application itself.


The user’s pod. It is external to our application. It is used by the application in order to preserve the privacy of our users. Will be provided by an external POD Provider.


Api to calculate coordinates and distances given the address from the pod.

PayPal API

PayPal provides developers with a powerfull api to process payments with PayPal, Credit cards and Sofort.

Level 1:


React application. Will contain the user interface as well as any client-side function the application may need.


The backend functionality will be provided by the firebase functions and Firebase DB Api.

Level 2:

These components are highly subject to change, given the early stage of the application development


The interface system the user will interact with.

DB Api

Built-in api already provided by firebase to access the database.


Provided by firebase. Serverless backend code that works via http requests. They allow JavaScript, TypeScript, Python and Go. They provide automatic vertical and horizontal escalation depending on the number of requests, ensuring availability and efficiency.

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.

6. Runtime View


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.


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


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

This is the process where the user logs in into the application and the system verifies it.

Login scenario

6.2. Purchasing scenario

Once the user has logged in he/she can purchase products, add them to the order and pay. This diagram represents a successful purchase.

Purchasing scenario

7. Deployment View


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.


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.


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.

Deployment view


Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. This diagram shows how the app components and their respective hardware devices are related to each other. It’s goal it’s to easily understand the technical infraestructure of the application.

Quality and/or Performance Features

Performance is mainly based on the user’s available resources(connection speed, device hardware, etc.) and the resources of the hosting server device (which depends on the price plan). We cannot control those things. To a lesser extent, the performance of the application will also depend on the node.js and react apps. We will make the required optimizations in order to maximize the performance and quality.

Mapping of Building Blocks to Infrastructure

Client Device

Device of the user (desktop, mobile). Must have internet connection


Firebase provides a database linked to the app.

DB Api

Corresponding api to perform queries to Firebase Database

Web Server

Firebase in which our app will be running.


Api to calculate coordinates and distances given a street, city, region…​

POD Provider

The pod provider we will be using. In our case, Solid Community. Will be in charge of providing the pods for the app users.

8. Cross-cutting Concepts


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


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.


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)


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 - Simple Class Diagram

UML Diagram

The main point of following this model is to allow the user to have a related lists of orders, containing the products purchased in that order and the date.

9. Design Decisions


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.


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


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

Decision Pros Cons

QA-1 Webstorm

Easy IDE to use very similar to IntellIJ

QA-2 Webapp

Better user experience, flexible access, easy setup.

Reduced speed, Internet reliance.

QA-3 Pod. Solid Community

Data security, all data in one place.

As the data is decentralized you need to rely on a different product and poor documentation.

QA-4 Firebase Hosting

It supports the deployment for the app. High availability.

Not very familiarized.

QA-5 Firebase Database

It stores the document-based database. High availability. Provides a clear web interface to administrate it. A protected and secure backend for accessing the storage is already provided.

Not very familiarized with document-based database.

QA-6 Firebase Functions

Serverless approach to provide the backend of our app. Has its own stored logs. High availability.

Very difficult to debug.

QA-7 Redux

Easy way of keeping the state of the application and using information of different pages

Hard configuration and none of us had any idea of how to use it before.

QA-8 Geocoder API

Fast coordinates resolution for addresses.

Very poor documentation for using it in TypeScript.

QA-9 PayPal API

Reliable payment gateway

A bit poor and unclear documentation

10. Quality Requirements

In this section our goal is to develop with more detail what it was said in the point 1.2, going in depth with the quality attributes.


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.


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

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


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


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

Quality requirement Quality scenario Priority


Our users' data must be extremely protected. The lowest amount of data our application takes, the better. Of course, always taking into account a decentralized delivery.



We are going to give as much security as we can, saving the data in a safe way. We will try to prevent any kind of attack or leak.



It is important to give the data to our users whenever they request, trying to reduce the technical failures to the minimal amount of time.



Whenever the users want to access their information or to save new data, we want the to use our system in an easy way for them.



Because our system will be in a constant develop and change, we want to design our implementation oriented to make this updates easier.


Resource utilization

Our objective in this part is to use the available resources in an efficient way, trying to complete other goals optimizing the resources we have.



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.


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.


Tabular or free form text.

11. Risks and Technical Debts

Table 1. Risks
Risks Considerations

Time for doing the project due to other courses

A good organization may solve this risk

Table 2. Technical Debts
Technical Debts Considerations

The usage of TypeScript and React

The team is not familiarized with the language so we may need to make own learning

This may be one of the biggest projects that we have faced

Collaboration and communication among the team will be crucial

12. Glossary


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.


You should clearly define your terms, so that all stakeholders

  • have an identical understanding of these terms

  • do not use synonyms and homonyms


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

Potentially more columns in case you need translations.

Term Definition


Solid is a specification that lets people store their data securely in decentralized data stores called Pods.


TypeScript is a strongly typed programming language that builds on JavaScript.


React is an open-source JavaScript library designed for building user interfaces.


Pods are where you store your data. Any kind of data can be stored in a Solid Pod. Once stored in a Pod, you control who can access your data.


Node.js is a platform built on JavaScript runtime for easily building fast and scalable network applications.


Platform to develop web applications and also to deploy them. Backend functions can be served from firebase.

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, Created by Dr. Peter Hruschka & Dr. Gernot Starke.