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.

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

1.1. Business Context

1.1.1. General Overview

The following graphic depicts 4 different examples how different RFs could potentially interact with our platform (OpenPrevo Hub).

Business Context
Figure 1. OpenPrevo Business Context

The following table explains the graphic above in more detail. All the different interfaces used for the communication between the different systems, would be pre-defined REST interfaces. Therefore a RF can implement their system independent of any programming language / framework. Every time the platform informs a RF about a match, it would send the payment information to the RF so that they have all information needed to transfer the money.

Table 1. OpenPrevo Business Context
System Description

OpenPrevo Hub

The Hub knows all different RFs which are registered on the platform and it is aware of their matching strategies. It is responsible for the matching.

EX1 / RF1

The first and most likely the default strategy would be, that the RF provides the data of people leaving or entering this RF. The platform fetches the data in regular intervals and matches it. The RF will be informed about the matches. Every match must be notified only once.

EX2 / RF2

If the RF does not want to provide an interface, it can also push the data into the platform and the platform stores the data. The platform still performs regularly its matching. The RF can consume the current matches via an API.

EX3 / RF3

Another strategy would be that the RF itself does the matching. Therefore the platform would ask the RF for matches during the execution of the matching. On the other hand the RF can also ask the platform for matches, e.g. when a new person enters into their system. Also here the platform would notify the RF if there is a match and provide the payment information. The goal of this strategy would be that the data never leaves the RF.

EX4 / RF4

There might be even the case that a RF wants to manually enter the data on the platform. This would most likely be a web application. The application would also display all matches for the entered data.

To limit the information that will be exchanged between the different RFs and the platform, every RF needs to provide a unique identifier (UID) for each person. In the case of a match the platform would then only inform the RF that we found a match for a certain UID and how the money needs to be transferred to the new RF.

1.1.2. MVP Business Context

To limit the scope for the MVP, we decided to implement the following solution. There will be only one of the above mentioned strategies (EX1/RF1), but we’ll provide two different implementations. One of the implementation would integrate with the PAKT system and on the other hand we’ll provide a simple implementation which could potentially be used by a small RF.

MVP Business Context
Figure 2. OpenPrevo MVP Business Context
Table 2. OpenPrevo Business Context
System Description

OpenPrevo Hub

The Hub fetches the data of the different RFs and is responsible for the matching.

PAKT

"Personen Applikation Kollektiv" which is used by different RFs to manage their customers. The TOE / COE will be extracted from the system and stored in a database that can be consumed by the OpenPrevo Client.

OpenPrevo Node

An implementation of the API that can be consumed by the OpenPrevo Hub. The node should be able to consume different data storages like e.g. a database or an Excel file.

Excel File

Could be a simple data exchange format for a small RF, if they’re not able to provide an integration into their system.

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

2.1. Technology Decisions

In the team we’ve decided to use the following technologies:

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

  • …​

3.1. Hub

3.1.1. main loop: data lookup, matching and notification

  • Node A: has a matching termination

  • Node B: has a matching commencement

Match Flow sequence diagram
Figure 3. OpenPrevo high-level MatchFlow sequence diagram

  1. Step: lookup data at nodes (in parallel)

    • ask nodes for commencement of employment(s)

    • ask nodes for termination of employment(s)

  2. Step: wait for response(s)

  3. Step: find match(es) in response(s)

  4. Step: notify about match(es)

    1. notify node B with matching commencement (passing the public key from node A with termination) and ask for payload

    2. notify node A with matching termination (and encrypted payload from B)

    3. optional (in grey)

      1. response from A to B

      2. pass the public key on notify from node B to A

      3. pass encrypted response from A to B

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

4.1. Security and data protection

Since we’re operating on very sensitive information, security is an important aspect of this project.

4.1.1. Authentication

When a Node and the Hub communicate with each other, both have to ensure that the communication partner is the one it claims to be. Our recommendation is to handle the authentication via server-certificates.

As this can be done with standard technologies (e.g. Spring Security) and does not add much value when demonstrating the functionality of OpenPrevo, we decided that authentication is out-of-scope for the MVP.

4.1.2. Symmetric Encryption

Currently we have implemented an end-to-end encryption for the exchange of the capital transfer information. Therefore the data is symmetrically encrypted via AES 256 by using a randomly generated Key and IV (inital vector) for every time it is being encrypted.

The key and the IV are then encrypted via an asymmetric encryption method, so that only the recipient is able to decrypt the key and the data itself. This is described in the next chapter.

4.1.3. Asymmetric Encryption

To encrypt the data asymmetrically, we’re using the RSA algorithm. Each participant of the OpenPrevo system needs to have a private and public-key pair. The public key will be provided via a public key registry. The private key must not leave a RFs environment.

4.1.4. Public Key Registry

To implement reliable authentication, signatures, and encryption via public- and private keys, one has to ensure that the public keys in use are really coming from the communication partner. In principal there are three approaches how public keys can be distributed:

  1. In addition to the hub, we setup a central key server for the public keys. Every time a node requires the public key of another node, it requests it from the server. Only authorised persons must be allowed to change the key of their node. In addition a notification should be sent out to the RF every time the public key of a node has been changed. One may wonder, why the RFs should trust the key server, if they do not trust the hub. Manipulations are much easier to discover, because the data is publicly visible and can be checked anytime. Technically an LDAP-server would probably already be sufficient, though specialized key servers exists, in particular in the PGP ecosystem.

  2. The management and distribution of public keys can be outsourced to an independent third party. There are service providers, who offer PKI as a service. With this solution, the distribution of the public keys would be completely separated from the organization that is running OpenPrevo. But it also means that all RFs have to trust the service provider.

  3. A completely different approach is a "web of trust". If a participant is sure, that a public key belongs to another participant, he or she can sign the public key. The more signatures the public key of a person has, who is unknown to me, the more I can trust his or her public key. Usually one sets a threshold when unknown keys can be trusted, e.g. if it has three or more signatures. One difficult question to be answered is how a new participant can get the first signatures. This approach is the least feasible in our context and should only be chosen, if the RFs cannot agree on a central instance that everybody trusts (internal or external).

It needs to be decided, if the public key registry will be maintained by the same team that maintains the hub, if it will be outsourced to an independent third party or if no central authority can be established and a "web of trust" has to be implemented. This is not a technical question and probably has to be discussed with potential customers first. Therefore it is probably out-of-scope of the MVP.

4.1.5. Signing

To make sure that the data (in our case the capital transfer information) originates really from the correct RF and not another party encrypted some information with ones public key, we sign the message before we sent it to the other RF. The message is signed with the private key of the RF, so only the RF itself is capable of doing this. For signing we’re using the SHA256withRSA algorithm.

4.1.6. Hashing

According to data protection guidelines in Switzerland we are not allowed to read any personal data of an insured person on our platform. Therefore, a RF is responsible for sending us only a hash of their data. For hashing we use SHA-512 algorithm.

4.1.7. Transport-Layer Security

In a production environment we recommend to use HTTPS exclusively. This can be achieved using standard technologies and is rather a question of deployment than one of development. Therefore we decided that this is not part of the MVP.

As an additional security measure, the Hub should be enhanced so that it accepts only HTTPS-Urls to communicate with the Nodes.

4.2. Legal compliance

4.2.1. FZG background

The old / previous retirement fund is legally obligated to transfer the FZL to the new / next retirement fund.
Übertragung an die neue Vorsorgeeinrichtung
Treten Versicherte in eine neue Vorsorgeeinrichtung ein, so hat die frühere Vorsorgeeinrichtung die Austrittsleistung an die neue zu überweisen.
— Freizügigkeitsgesetz
Artikel 3 Absatz 1
The insured person has no choice: only if no new retirement fund is available he has a choice.
Erhaltung des Vorsorgeschutzes in anderer Form
Versicherte, die nicht in eine neue Vorsorgeeinrichtung eintreten, haben ihrer Vorsorgeeinrichtung mitzuteilen, in welcher zulässigen Form sie den Vorsorgeschutz erhalten wollen.
— Freizügigkeitsgesetz
Artikel 4 Absatz 1
When entering a new retirement fund the FZE has to transfer the vested benefits to the new retirement fund.
Treten die Versicherten in eine neue Vorsorgeeinrichtung ein, so müssen die Freizügigkeitseinrichtungen das Vorsorgekapital für die Erhaltung des Vorsorgeschutzes der neuen Vorsorgeeinrichtung überweisen.
— Freizügigkeitsgesetz
Artikel 4 Absatz 2bis
The new retirement fund is allowed to claim the FZL from the previous retirment fund.
Recht auf Einsicht und Einforderung
Die Vorsorgeeinrichtung kann die Austrittsleistung aus dem früheren Vorsorgeverhältnis sowie das Vorsorgekapital aus einer Form der Vorsorgeschutzerhaltung für Rechnung der Versicherten einfordern.
— Freizügigkeitsgesetz
Artikel 11 Absatz 2

4.2.2. BVG background

Neutral institutions assigned with tasks (performing, controlling, supervision) related to the federal BVG law are allowed to process the necessary data.
Datenbekanntgabe
Sofern kein überwiegendes Privatinteresse entgegensteht, dürfen Daten bekannt gegeben werden an a. andere mit der Durchführung sowie der Kontrolle oder der Beaufsichtigung der Durchführung dieses Gesetzes betrauten Organe, wenn sie für die Erfüllung der ihnen nach diesem Gesetz übertragenen Aufgaben erforderlich sind;
— Berufliche Vorsorge Gesetz
Artikel 86a Abschnitt g/a

4.2.3. "Verordnung des EDI" background: Usage of OASI numbers

We process OASI numbers in a systematic way without mutations, hence this by-law is applicable for OpenPrevo.
Geltungsbereich
Für die systematische Verwendung der Versichertennummer in Datensammlungen, in denen keinerlei Mutationen im Zusammenhang mit der Versichertennummer vorgenommen werden, sind nur die Bestimmungen nach den Artikeln 6-8 anwendbar.
— Verordnung des EDI
Artikel 2 Absatz 2
Risk analysis and minimal security requirements
Massnahmen zum Schutz vor missbräuchlicher Verwendung - Grundsätze
2) Wird die Versichertennummer in komplexen Systemen systematisch verwendet, so sind die nötigen Schutzmassnahmen gestützt auf eine detaillierte Risikoanalyse zu treffen. Die Analyse hat insbesondere dem Risiko einer unerlaubten Zusammenführung von Datensammlungen Rechnung zu tragen. 3) Beim Betrieb von Informatikmitteln und Datenspeichern sind die minimalen Sicherheitsvorgaben nach Anhang 2 einzuhalten.
— Verordnung des EDI
Artikel 6 Absatz 2 und 3
Transferred data in public IT infrastructure has to be encrypted.
Massnahmen zum Schutz vor missbräuchlicher Verwendung - Datenübertragung über öffentliche Netze
Werden Datensammlungen mit Datensätzen, welche die Versichertennummer enthalten, über ein öffentliches Netz übertragen, so sind sie nach dem Stand der Technik zu verschlüsseln.
— Verordnung des EDI
Artikel 7
Encrypted access only for authenticated and authorized partners with active auditing of activities and events
Minimale Sicherheitsvorgaben für den Betrieb von Informatikmitteln und Datenspeichern, die bei der systematischen Verwendung der Versichertennummern eingesetzt werden
1) […​] Beim Einsatz mobiler Informatikmittel und Datenspeicher muss mit Hilfe von dem Stand der Technik entsprechenden kryptografischen Verfahren (Datenverschlüsselung) sichergestellt sein, dass die Nutzung bzw. der Zugriff für Unberechtigte nicht möglich ist. 2) Der Zugriff auf Informatikmittel und Datenspeicher muss mit Hilfe von angemessenen, dem Stand der Technik und der Risikolage entsprechenden Informatiksicherheitsmassnahmen geschützt sein. […​] 3) Benutzer und Benutzerinnen, die auf Informatikmittel und Datenspeicher zugreifen, müssen authentifiziert werden. […​] 5) Auf Informatiksystemen sind wichtige Aktivitäten und Ereignisse aufzuzeichnen und regelmässig auszuwerten. […​]
— Verordnung des EDI
Anhang 2

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

acronym English Deutsch Française Italiano

OASI

Old-age and survivor’s insurance

Alters- und Hinterlassenenversicherung (AHV)

Assurance-vieillesse et survivants (AVS)

Assicurazione vecchiaia e superstiti (AVS)

AF

Auxiliary fund

Auffangeinrichtung

Institution supplétive

Istituto Collettore

Benefits

Leistungen

Prestations

Prestazioni

BVG

Berufliche Vorsorge Gesetz

Loi fédérale sur la prévoyance professionnelle vieillesse, survivants et invalidité (LPP)

Legge federale sulla previdenza professionale per la vecchiaia, i superstiti e l’invalidità (LPP)

CCO

Central Compensation Office

Zentrale Ausgleichsstelle (ZAS)

La Centrale de compensation (CdC)

L’Ufficio centrale di compensazione (UCC)

CF

Collective Foundation

Sammelstiftung

Fondation collective

Fondazione collettiva

CO

Compensation Office

Ausgleichskasse

Caisse de compensation

Cassa di compensazione

COE

Commencement of Employment

Diensteintritt

Entrée en service

Entrata in servizio

EC

Employer Change

Stellenwechsel

EDI

Eidgenössische Departement des Innern

Le Département fédéral de l’intérieur (DFI)

Dipartimento federale dell’interno (DFI)

ESR

inpayment slip with reference number (ISR)

Einzahlungsschein mit Referenznummer

bulletin de versement avec numéro de référence (BVR)

bollettino di versamento con numero di riferimento (BVR)

FZG

Federal law on vested benefits

Freizügigkeitsgesetz

Loi sur le libre passage (LFLP)

Legge sul libero passaggio (LFLP)

OPP

Occupational pension plan

Berufliche Vorsorge (BV)

Prévoyance professionelle (PP)

Previdenza professionale (PP)

PF

Pension Fund

Pensionskasse (PK)

Caisse de pensions (CP)

Cassa pensioni (CP)

PAKT

Personen Applikation Kollektiv

Retirement

Pensionierung

Retraite

Pensionamento

RF

Retirement fund

Vorsorgeeinrichtung (VE)

Institution de prévoyance

istituto di previdenza

Foundation

Stiftung

Fondation

Fondazione

SCO

Swiss Compensation Office

Schweizerische Ausgleichskasse (SAK)

Caisse suisse de compensation (CSC)

Cassa svizzera di compensazione (CSC)

TB

Termination benefit

Austrittsleistung

Prestation de sortie

Prestazione di uscita

TOE

Termination of Employment

Dienstaustritt

Sortie de service

Uscita dal servizio

UID

Enterprise Identification Number

Unternehmens-Identifikationsnummer

Numéro d’identification des entreprises (IDE)

Numero d’identificazione delle imprese (IDI)

VB

Vested Benefits

Freizügigkeitsleistung (FZL)

prestation de libre passage

prestazione di libero passaggio

VBI

Vested Benefits Institution

Freizügigkeitseinrichtung (FZE)

institution de libre passage

istituto di libero passaggio

VBA

Vested Benefits Account

Freizügigkeitskonto

Compte de libre passage

Conto di libero passaggio

VBP

Vested Benefits Policy

Freizügigkeitspolice

Police de libre passage

Polizza di libero passaggio