Arc42 by Example Software Architecture Documentation in Practice 3rd Edition 3nbsped
Arc42 by Example Software Architecture Documentation in Practice 3rd Edition 3nbsped
* * * * *
This is a Leanpub book. Leanpub empowers authors and publishers with the
Lean Publishing process. Lean Publishing is the act of publishing an in-progress
ebook using lightweight tools and many iterations to get reader feedback, pivot
until you have the right book and build traction once you do.
* * * * *
© 2016 - 2023 Gernot Starke, Michael Simons, Stefan Zörner, Ralf D. Müller
and Hendrik Lösch
Table of Contents
Preface
Acknowledgements
Conventions
Disclaimer
I - Introduction
I.1 What is arc42?
I.2 Why this Book?
I.3 What this Book is Not
I.4 Overview of the Examples
I.5 Table of arc42 Topics
II. HTML Sanity Checking
II.1. Introduction and Goals
II.2 Constraints
II.3 System Scope and Context
II.4 Solution Strategy
II.5 Building Block View
II.6 Runtime View
II.7 Deployment view
II.8 Cross-cutting Concepts
II.9 Architecture Decisions
II.10 Quality Requirements
II.11 Risks and Technical Debt
II.12 Glossary
III - Mass Market Customer Relationship Management
III.1 Introduction and Goals
III.2 Constraints
III.3 System Scope and Context
III.4 Solution Strategy
III.5 Building Block View
III.6 Runtime View
III.7 Deployment View
III.8 Cross-Cutting Concepts
III.9 Architecture Decisions
III.10 Quality Requirements
III.11 Risks
III.12 Glossary
IV - biking2
IV.1 Introduction and Goals
IV.2 Constraints
IV.3 System Scope and Context
IV.4 Solution Strategy
IV.5 Building Block View
IV.6 Runtime View
IV.7 Deployment View
IV.8 Cross-cutting Concepts
IV.9 Architecture Decisions
IV.10 Quality Requirements
IV.11 Risks and Technical Debt
IV.12 Glossary
V - DokChess
V.1 Introduction and Goals
V.2 Constraints
V.3 System Scope and Context
V.4 Solution Strategy
V.5 Building Block View
V.6 Runtime View
V.7 Deployment View
V.8 Cross-cutting Concepts
V.9 Architecture Decisions
V.10 Quality Requirements
V.11 Risks and Technical Debts
V.12 Glossary
VI - docToolchain
VI.1 Introduction and Goals
VI.2 Constraints
VI.3 System Scope and Context
VI.4 Solution Strategy
VI.5 Building Block View
VI.6 Runtime View
VI.7 Deployment View
VI.8 Cross-cutting Concepts
VI.9 Architecture Decisions
VI.10 Quality Requirements
VI.11 Risks and Technical Debt
VI.12 Glossary
VII - Foto Max
VII.1 About this document
VII.2 Introduction and Goals
VII.3 Quality Requirements
VII.4 Constraints
VII.5 System Scope and Context
VII.6 Solution Strategy
VII.7 Building Block View
VII.8 Runtime View
VII.9 Deployment View
VII.10 Cross-cutting Concepts
VII.11 Architecture Decisions
VII.12 Risks & Technical Debt
VII.13 Glossary
VII.14 Organizational Topics
VIII - Mac-OS Menubar Application
The Authors
Gernot Starke
Hendrik Lösch
Michael Simons
Stefan Zörner
Ralf D. Müller
Contacting the Authors
Further Reading
Notes
Preface
Acknowledgements
Gernot
Long ago, on a winters’ day in 2004, I sat together with Peter Hruschka, a long-
time friend of mine and discussed one1 of our mutual favorite subjects - structure
and concepts of software systems.
“If we only had a similar template for software architecture”, Peter complained,
and continued “countless IT projects could save big time and money”… My
developer-soul added a silent wish: “If this was great, it could even take the
ugliness out of documentation”.
We both looked at each other, and within this second decided to create exactly
this: A template for software architecture documentation (and communication),
that is highly practical, allows for simple and efficient documentation, is usable
for all kinds of stakeholders and could facilitate software architecture
documentation. And of course, it had to be open source, completely free for
organizations to use.
Since then, Peter and myself have used arc42 in dozens of different IT systems
within various domains. It has found significant acceptance within small,
medium and large organizations throughout the world. We wrote more many
articles around it, taught it to more than 1000 (!) IT professionals and included it
in several of our software architecture-related books.
Thanx Peter for starting this wild ride with me. And, of course, for your lectures
on cooking.
Thanx to my wife Cheffe Uli and my kids Lynn and Per for allowing dad to
(once more) sit on the big red chair and ponder about another book project…
You’re the best, and I call myself incredibly lucky to have you!
Thanx to my parents, who, back in 1985, when the computer stuff was regarded
to be something between crime and witchcraft, they encouraged my to buy one
(an Apple-2, by the way) and didn’t even object when I wanted to study
computer science instead of something (by that time) more serious. You’re great!
Michael
I’ve met Gernot and Peter (Hruschka) as instructors on a training at the end of
2015. The training was called “Mastering Software Architectures” and I learned
an awful lot from both of them, not only the knowledge they shared but how
they both shared it. By the end of the training I could call myself “Certified
Professional for Software Architecture”, but what I really took home was the
wish structure, document and communicate my own projects like Peter and
Gernot proposed and that’s why the current documentation of my pet project
biking2 was created.
Since then I used arc42 based documentations several times: As well as for in-
house products and also at projects and consultancy gigs. The best feedback was
something along the lines: “Wow, now we’ve got an actual idea about what is
going on in this module.” What helped that special project a lot was the fact that
we set fully on Asciidoctor and the “Code as documentation and documentation
as code” approach I described in depth in my blog.
So here’s to Gernot and Peter: Thanks for your inspiration and the idea for arc42.
StefanZ
Ralf D. Müller
On this journey, I have met many people who helped me along this way -
impossible to name all of them.
However my biggest “Thanx!” goes out to Gernot who always encouraged me to
do my next step and helped me along the way.
Thank you, Peter and Gernot for pushing my architectural skills to the next level
through their superb training workshops.
Thanx to Jakub Jabłoński and Peter for their review of the architecture - You
gave great feedback!
Last but not least, I have to thank my family for their patience while I spent too
much time with my notebook!
Hendrik Lösch
Like some of my fellow authors, I met Gernot at conferences and then got to
know him better in a workshop. At that time I had already specialized in
restructuring legacy software and since I come from the field of cyber-physical
systems, I noticed some peculiarities. Bold as I was, I suggested to Gernot that
we could write a book together.
My biggest thanks go to both Gernot and Stefan. The work of both has helped
me very often in the past years. It is a great honor for me to be able to publish
something together with them that helps other people in their work.
I also want to say a big thank you to Attila Bertok who reviewed my part of the
book and was an invaluable help in translating it from German into English.
All of us
We use roman chapter numbers (I, II, III etc), so we can have the arabic numbers
within chapters in alignment with the arc42 sections…
In the sections within chapters, we add the chapter-prefix only for the top-level
sections. That leads to the following structure:
Explanations:
The first example (HTML Sanity Checking) contains short explanations on the arc42 sections,
formatted like this one.
In this book, we keep these explanations to a bare minimum, as there are other
books extensively covering arc42 background and foundations.
Disclaimer
We like to add a few words of caution before we dive into arc42 examples:
We show you quite pragmatic approaches to software and system architecture documentation,
based upon the (also pragmatic) arc42 template. Although fine for many kinds of systems, this
pragmatism is not appropriate for critical or high-risk systems, developed or operated under
strict safety-, security- or similar requirements.
We, the authors, cannot take any responsibility if you decide to use arc42 or any other approach
shown in this book.
The content of this book has been created with care and to the best of our
knowledge. However, we cannot assume any liability for the up-to-dateness,
completeness, accuracy or suitability to specific situations of any of the pages.
I - Introduction
It answers the following two questions in a pragmatic way, but can be tailored to
your specific needs:
Figure I.1 gives you the big picture: It shows a (slightly simplified) overview of
the structure of arc42.
Figure I.1
Compare arc42 to a cabinet with drawers: the drawers are clearly marked with
labels indicating the content of each drawer. arc42 contains 12 such drawers (a
few more than you see in the picture above). The meaning of these arc42
drawers is easy to understand.
Therefore, arc42 offers you a simple and clear
structure to document and communicate your
(complex!) system. Starting with the goals
and requirements for your system and its
embedding into its environment you can
provide the important stakeholder of your
system with adequate information about the
arc42 metaphor
architecture.
Individuals and organizations using arc42 especially like two things about it:
Why 42?
You’re kidding, aren’t you? Ever heard of Douglas Adams, the (very British) and
already deceased sci-fi writer… his novel “Hitchhikers Guide to The Galaxy”
calls 42 the:
With the latest release (V7) of arc42 in January 2017, the project now has
extensive online help and FAQ (frequently asked questions) available:
Examples are often better suited to show how things can work than lengthy explanations.
arc42 users have often asked for examples to complement the (quite extensive)
conceptual documentation of the template that was, unfortunately, only available
in German for several years.
There were a few approaches to illustrate how arc42 can be used in real-world
applications, but those were (and still are) scattered around numerous sources,
and not carefully curated.
Software architecture
Architecture and Design Patterns
Modeling, especially UML
Chinese cooking (but propably you didn’t expect that here…)
I.4 Overview of the Examples
Therefore it has been quite difficult to find practical examples which we can
freely write and talk about.
Now let’s get an overview of the examples that are waiting in the rest of this
book…
A tiny open source system to check HTML files for semantic errors, like broken
cross references, missing images, unused images and similar stuff.
Gernot wrote the initial version of this system himself when working on a rather
large (100+pages) documentation based upon the AsciiDoctor markup language.
We are reasonably sure you know these 86×54mm plastic cards (experts call
them ISO/IEC 7810). Chances are you even own several of these cards. In case it
contains your portrait photo, chances are high it was produced by a system like
MaMa-CRM…
biking2
biking2 or “Michis milage” is a web based application for tracking biking related
activities. It allows the user to track the covered milage, collect GPS tracks of
routes, convert them to different formats, track the location of the user and
publish pictures of bike tours.
docToolchain
Foto Max
Foto Max is a made-up company that offers solutions for ordering photos. The
software architecture in this book describes how the software is implemented to
be used on the company’s devices.
MiniMenu
Surely one of the leanest architecture documentations you will ever encounter.
Captures some design and implementation decisions for a tiny Mac-OS menu
bar application.
The main goal is to show that arc42 even works for very small systems.
This page helps you to quickly find the arc42 topics you’re looking for: For each
section of arc42, you find references to each of this books’ examples… The
digits after the links denote the size of section in the respective example. We
marked the most extensive or complete example in bold, so you can easily
recognize it.
3. System Scope and HtmlSC (3), MaMa-CRM (4), biking2 (3), DokChess
Context (2), docToolchain (4)
11. Risks and HtmlSC (1), MaMa-CRM (1), biking2 (1), DokChess
Technical Debt (2), docToolchain (2)
At the beginning of each section you find short explanations, formatted in boxes like this.
This section shows the driving forces for architecturally relevant decisions and important use-
cases or features, summarized in a few sentences. If possible, refer to existing requirements
documentation.
The main goal of this section is enabling your stakeholders to understand the solution, which is
detailed in arc42-sections 3 to 12.
You like to briefly explain important goals and requirements, use-cases or features of the
system. If available, refer to existing requirements documentation.
Most important: Readers can understand the central tasks of the system, before they encounter
the architecture of the system (starting with arc42-section 3).
The overall goal of HtmlSC is to create neat and clear reports, showing errors
within HTML files. Below you find a sample report.
Sample Report
HtmlSanityCheck (HtmlSC) checks HTML for semantic errors, like broken links
and missing images. It has been created to support authors who create HTML as
output format.
Basic Usage
ID Requirement Explanation
Check HTML
G- HtmlSC checks HTML files for semantic errors, like broken
for semantic
1 links.
errors
Gradle and
G-
Maven HtmlSC can be run/used as Gradle and Maven plugin.
2
Plugin
Required Checks
Check Explanation
Missing
Check all image tags if the referenced image files exist.
images
Broken
Check all internal links from anchor-tags (`href=”#XYZ”) if the
internal
link targets “XYZ” are defined.
links
Missing
local Check if referenced files (e.g. css, js, pdf) are missing.
resources
Malformed
Check all links for syntactical correctness.
links
Illegal link
Check for malformed or illegal anchors (link targets).
targets
Broken
external Check external links for both syntax and availability.
links
You want to understand the quality goals (aka architeture goals), so you can align architecture
and design decisions with these goals.
These (usually long term) quality goals diverge from the (usually short term) goals of
development projects. Mind the difference! See also arc42-section 10.
Quality
Priority Scenario
Goal
1 Correctness Every broken internal link (cross reference) is found.
1.3 Stakeholders
You want an overview of persons, roles or organizations that affect, are affected by or can
contribute to the system and its architecture. Make the concrete expectations of these
stakeholders with respect to the architecture and its documentation explicit. Collect these in a
simple table.
Remark: For our simple HtmlSC example we have an extremely limited number
of stakeholders, in real-life you will most likely have many more stakeholders!
You want to know the constraints that restrict your freedom of design decisions or the
development process. Such constraints are often imposed by organizations across several IT
systems.
You want to know the boundaries and scope of the system to distinguish it from neighboring
systems. The context identifies the systems relevant external interfaces.
You want to identify all neighboring systems and the different kinds of (business) data or
events that are exchanged between your system and its neighbors.
Business context
Neighbor Description
documents software with toolchain that generates html. Wants to
user
ensure that links within this HTML are valid.
build
system mostly Gradle
local
HtmlSC reads and parses local HTML files and performs sanity
HTML
checks within those.
files
local
image HtmlSC checks if linked images exist as (local) files.
files
You like to know about the technical or physical infrastucture of your system, together with
physical channels or protocols.
The following diagram shows the participating computers (nodes) with their
technical connections plus the major artifacts of HtmlSC, the hsc-plugin-binary.
Deployment context
Node /
Description
Artifact
hsc-
where development of HtmlSC takes place
development
hsc user where arbitrary documentation takes place with html as output
computer formats.
Gradle build script configuring (among other things) the HtmlSC
build.gradle
plugin to perform the HTML checking.
You need a brief summary and explanation of the fundamental solution ideas and strategies.
These key ideas should be familiar to everyone involved in development and architecture.
Briefly explain how you achieve the most important quality requirements.
The building block view explains the static decomposition of the system into building blocks
(modules, components, subsystems, packages…) and their relationships. It shows the overall
structure of the source code.
Whitebox (HtmlSC)
Contained Blackboxes:
Building
Description
block
HSC Core HTML parsing and sanity checking
NetUtil
package org.aim42.inet, checks for internet connectivity,
configuration of http status codes
HSC
Graphical (planned, not implemented)
UI
5.2 Building Blocks - Level 2
HSC-Core (Whitebox)
configuration,
parsing and handling HTML input,
checking,
creating suggestions and
collecting checking results
Contained Blackboxes:
The abstract class Checker provides the uniform interface (public void
check()) to different checking algorithms.
For a given input (target), Suggester searches within a set of possible values
(options) to find the n most similar values. For example:
Target = “McDown”
Options = {“McUp”, “McDon”, “Mickey”}
The resulting suggestion would be “McDon”, because it has the greatest
similarity to the target “McDown”.
Broken image links: Compares the name of the missing image with all
available image file names to find the closest match.
Missing cross references (broken internal links): Compares the broken link
with all available link targets (anchors).
Rationale: This structures follows the hierarchy of checks, managing results for:
Contained Blackboxes:
SingleCheckResults
Results for a single type of check (e.g. missing-
images check or broken-internal-link check)
Finding
A single finding, (e.g. “image ‘logo.png’
missing”). Can contain suggestions.
II.6 Runtime View
The runtime view shows behavior, interactions and runtime dependencies of the building
blocks in form of concrete scenarios.
It helps you to understand how the building blocks of your systems fulfill their respective tasks
at runtime, and how they communicate/interact with each other at runtime.
Explanation:
For stable operation, you need to know the technical infrastructure in which your system will
run. This is especially important if your software is distributed or deployed on several different
machines, application servers or containers.
Sometimes you need to know about different environments (e.g. development, test,
production). For large commercial or web systems, aspects such as scalability, clustering,
automatic provisioning, firewalls and load balancing also play an important role.
Node /
Description
Artifact
hsc plugin
Compiled version of HtmlSC, including required dependencies.
binary
hsc-
Development environment
development
hsc user
Where documentation is created and compiled to HTML.
computer
The three nodes (computers) shown in the diagram above are connected via
Internet.
Prerequisites:
HtmlSC developers need a Java development kit, Groovy, Gradle plus the
JSoup HTML parser.
HtmlSC users need a Java runtime (> 1.6) plus a build file named
build.gradle. See below for a complete example.
Example for build.gradle
1 buildscript {
2 repositories {
3 mavenLocal()
4 maven {
5 url "https://plugins.gradle.org/m2/"
6 }
7 }
8 dependencies {
9 // in case of mavenLocal(), the following line is valid:
10 classpath(group: 'org.aim42',
11
12 // in case of using the official Gradle plugin repository:
13 //classpath (group: 'gradle.plugin.org.aim42',
14 name: 'htmlSanityCheck', version: '1.0.0-RC-3')
15 }
16 }
17
18 plugins {
19 id 'org.asciidoctor.convert' version '1.5.8'
20 }
21
22
23 // ==== path definitions =====
24 ext {
25 srcDir = "$projectDir/src/docs/asciidoc"
26
27 // location of images used in AsciiDoc documentation
28 srcImagesPath = "$srcDir/images"
29
30 // (input for htmlSanityCheck)
31 htmlOutputPath = "$buildDir"
32
33 targetImagesPath = "$buildDir/images"
34 }
35
36 // ==== asciidoctor ==========
37 apply plugin: 'org.asciidoctor.convert'
38
39 asciidoctor {
40 outputDir = file(buildDir)
41 sourceDir = file(srcDir)
42
43 sources {
44 include "many-errors.adoc", "no-errors.adoc" }
45
46 attributes = [
47 doctype : 'book',
48 icons : 'font',
49 sectlink : true,
50 sectanchors: true ]
51
52 resources {
53 from(srcImagesPath) { include '**' }
54 into "./images" }
55 }
56
57 // ========================================================
58 apply plugin: 'org.aim42.htmlSanityCheck'
59
60 htmlSanityCheck {
61 // ensure asciidoctor->html runs first
62 // and images are copied to build directory
63
64 dependsOn asciidoctor
65
66 sourceDir = new File("${buildDir}/html5")
67
68 // files to check, in Set-notation
69 sourceDocuments = ["many-errors.html", "no-errors.html"]
70
71 // fail the build if any error is encountered
72 failOnErrors = false
73
74 // set the http connection timeout to 2 secs
75 httpConnectionTimeout = 2000
76
77 ignoreLocalHost = false
78 ignoreIPAddresses = false
79 }
80
81 defaultTasks 'htmlSanityCheck'
II.8 Cross-cutting Concepts
You should explain cross-cutting and ubiquitous rules of your system. arc42 calls them
concepts: They often affect multiple building blocks and are relevant in several parts of the
system and its implementation. Examples include:
Term Description
Anchor Html element to create ->Links. Contains link-target in the form <a
href="link-target">
Cross Link from one part of the document to another part within the same
Reference document. Special form of ->Internal Link, with a ->Link Target in
the same document.
External
Link to another page or resource at another domain.
Link
Internal Link to another section of the same page or to another page of the
Link same domain. Also called ->Cross Reference or Local Link.
Any a reference in the ->Html Page that lets you display or activate
another part of this document (->Internal Link) or another
Link document, image or resource (can be either ->Internal (local) or -
>External Link). Every link leads from the Link Source to the Link
Target.
Local
Local file, either other Html files or other types (e.g. pdf, docx)
Resource
Run The overall results of checking a number of pages (at least one
Result page).
Single
Page A collection of all checks of a single ->Html Page.
Result
Remark: For many web developers or HTML experts the following information
on URI syntax might be completely evident. As we wrote this book also for
different kind of people, we included this information anyhow.
Their general structure is depicted in the following figure - you also find a unit
test below.
Component Description
abstract base class, containing the template method
Checker
check() plus the public method performCheck()
InternalLinksChecker
checks if cross references (links referenced within
the page) exist
8.4 Reporting
HtmlSC supports the following output (== reporting) formats and destinations:
The reporting subsystem uses the template method pattern to allow different
output formats (e.g. Console and HTML). The overall structure of reports is
always the same.
The (generic and abstract) reporting is implemented in the abstract Reporter
class as follows:
Report findings using TemplateMethod pattern
1 /**
2 * main entry point for reporting - to be called when a report is reque\
3 sted
4 * Uses template-method to delegate concrete implementations to subclas\
5 ses
6 */
7 public void reportFindings() {
8 initReport() // (1)
9 reportOverallSummary() // (2)
10 reportAllPages() // (3)
11 closeReport() // (4)
12 }
13
14 private void reportAllPages() {
15 pageResults.each { pageResult ->
16 reportPageSummary( pageResult ) // (5)
17 pageResult.singleCheckResults.each { resultForOneCheck ->
18 reportSingleCheckSummary( resultForOneCheck ) // (6)
19 reportSingleCheckDetails( resultForOneCheck ) // (7)
20 reportPageFooter()
21 }
22 }
1. initialize the report, e.g. create and open the file, copy css-, javascript and
image files.
2. create the overall summary, with the overall success percentage and a list of
all checked pages with their success rate.
3. iterate over all pages
4. write report footer - in HTML report also create back-to-top-link
5. for a single page, report the number of checks and problems plus the
success rate
6. for every singleCheck on that page, report a summary and
7. all detailed findings for a singleCheck.
8. for every checked page, create a footer, page break or similar to graphically
distinguish pages between each other.
You like to understand important, huge, expensive, risky or otherwise special architecture and
design decisions.
In the current version of HtmlSC we won’t check external links. These checks
have been postponed to later versions.
[quote] jsoup is a Java library for working with real-world HTML. It provides a
very convenient API for extracting and manipulating data, using the best of
DOM, CSS, and jQuery-like methods.
Decision Criteria:
jsoup: a plain HTML parser without any dependencies (!) and a rich API to
access all HTML elements in DOM-like syntax. Clear winner!
HTTPUnit: a testing framework for web applications and -sites. Its main
focus is web testing and it suffers from a large number of dependencies.
HtmlCleaner
II.10 Quality Requirements
You want to know specific and operational quality requirements, at best in form of a specific
quality tree. This section completes, augments or refines the top-quality goals already given in
arc42-section 1.2.
Remark: For our small example, such a quality tree is overly extensive…
whereas in real-live systems we’ve seen quality trees with more than 100
scenarios. Therefore, we stick to (repeating) a few scenarios here.
Quality Scenarios
Attribute Description
Correctness Every broken internal link will be found.
You want to know the technical risks of your system, so you can address potential future
problems.
In addition you want to support your management stakeholders (i.e. project management,
product owner) by identifying technical risks.
Remark: In our small example we don’t see any real risks for architecture and
implementation. Therefore the risks shown below are a bit artificial…
Risk Description
Bottleneck with Currently only one single developer has access rights to
access rights on deploy new versions of HtmlSC on public servers like
public repositories Bintray or Gradle plugin portal.
Risk Description
System might
In case AsciiDoc or Markdown processors implement HTML
become
checking natively, HtmlSC might become obsolete.
obsolete
II.12 Glossary
You need to understand the most important domain terms and expressions, that stakeholders
use when communicating about the system, its interfaces, goals and requirements.
The glossary is one manifestation of our pledge for “explicit, not implicit”, as it associates
words or terms with sense, meaning and semantics.
In the case of our small example, the terms given here should be good friends to
most developers. You find a more interesting version of the glossary in section
II-8.1.
Term Definition
A reference within an →HTMLPage. Points to
Link
→LinkTarget
The team that built the system consisted of 7-10 persons working in 2-4 week
iterations for about 15 months.
Me (Gernot Starke) had the honor to be part of that team in a responsible role.
The original client allowed me to talk and write about the system without
disclosing the company name. I was not allowed to use any of the original
documentation or source code.
Thanx to Thorsten, Sven, Arno and a few unnamed other guys for great
cooperation and a successful finish.
III.1 Introduction and Goals
Let’s clarify MaMa-CRM’s scope with a few brief examples (you’ll find more
details in the requirements overview):
For an explanation of the terms campaign, activity, mandator and partner, please refer to the
glossary in chapter 12
MoPho is a (hypothetical) mobile phone provider with a large customer base and
a variety of different tariff options (flat fee, time-based, volume-based etc.).
Some of these tariffs or tariff combinations are not marketable any longer (a
shorthand for “MoPho does not earn its’ desired profit from them… - but that’s
another story). Others are technically outdated.
For the phone service provider MoPho, the primary advantage is the centralized
interface to all customer interaction: All processes required to conduct this
crucial campaign are handled by MaMa-CRM, without intervention by MoPho.
Very practical for MoPho is the nearly unlimited flexibility of MaMa-CRM to
import and export a variety of different data formats. This flexibility enables
MaMa-CRM to easily incorporate new campaign partners (like a second scan
service provider, an additional email-service provider or web hosting partner).
The following section gives an overview of such a configuration for the MoPho
campaign described in the previous section.
Define and configure required data attributes and additional classes, usually this
information is completely provided by the mandator.
This data (e.g. contract-, tariff-, offer- and other business-specific entities or
attributes) are modeled as extensions of the MaMa base model in UML.
Existing tariff
List of potential new tariffs
Contract number
Validity period of existing tariff
Validity period of new tariff
What is the required flow of activities, what needs to happen under which
conditions (including plausibility checks).
It’s especially important to report about activities subject to a charge (aka having
financial consequences). Although MaMa-CRM is not responsible for the
resulting billing and payment processes, mandators and partners need reliable
and trustworthy reports about such activities.
MaMa-CRM follows a very strict data protection policy: All data processes in
campaigns is somehow related to clients and needs to be kept strictly
confidential. Mandators always remain owners of all such data, from whatever
partner it is transferred to MaMa by whatever activities.
After a campaign officially ends, all (!) data including backups, configurations,
data and metadata needs to be deleted7.
1.2 Quality Goals
Simply stated, MaMa is a data hub with flexibility in several aspects: It imports
data (aspect 1) coming over various transmission channels (aspect 2) executes a
set of specific business rules (aspect 3) to determine further activities to be
performed with this data. Such activities consist of data exports (aspect 4) to
certain business partners (like print-, scan- or fax service providers, call centers
and the like).
MaMa always deals with variants of clientdata - the most simple version could
look like an instance of the following class definition:
Generic Definition of Client Record
1 public class Client
2 String primaryKey
3 String lastName
4 String firstName
5 Date birthDate
6 String title
7 Address postalAddress
MaMa needs to import such data from various campaign partners. These partners
operates their own IT systems with their own data formats. They will export the
affected data records in some format (see below) of their choice. MaMa needs to
handle many such formats:
Standard transmission protocols (ftp, sftp, http, https) as both client and
server
Compressed,
Encrypted
Creation of checksums, at least with counters, MD5 and SHA-1
Mandator- or campaign specific credentials for secure transmission
Transmission metadata, i.e.: Count the number of successful transmissions
and send the number of the last successful transmissions as a prefix to the
next transmission.
Now that MaMa has received and processed data (by import, transmission and
rule processing), it needs to send data to the campaign partners. Analogous to
data import, these receiving partners have very specific requirements concerning
data formats.
Prio 1: Flexibility
MaMa-CRM can:
import and export (configurable) CSV and fix-record-length data.
import and export data via ftp, sftp, http and https, as client and server.
handle compressed data. Compression algorithm is configurable per
activity, standard lossless have to be supported.
handle encrypted data. Security credentials need to be exchanged between
parties prior to campaigns during campaign setup. PGP or derivatives are
recommended.
handle hashes or similar transmission metadata, configurable per campaign.
For all these topics, InDAC administrators can fully configure all campaign-
specific aspects within one workday.
Prio 2: Security
MaMa will keep all its client and campaign related data safe. It shall never be
possible for campaign-external parties to access data or metadata.
MaMa can fully process 250.000 scanned return letters within 24 hours.
Periodical cooperation
Management Requires flexible and performant
on current and changed
of contractee foundation for current and future
requirements, solution
(InDAC) business segments.
approaches.
Software
developers
Design MaMa internal structure, Active participation in
participating in
implement building blocks. technical decisions.
MaMa
implementation
Operational constraints
Every MaMa instance communicates with a single mandator and one or more
partner organizations, like shown in the diagram below. Partners are external
service providers, for example printer, mail delivery services, scan services, call-
center or internet hosting providers.
Interface /
Neighbor Exchanged Data
system
Client and
(inbound, from mandator) Mandator transfers campaign and
campaign
client master data to MaMa-CRM.
master data
Final results
(outbound, MaMa transfers final campaign results back to mandator. This is
to the ultimate goal of the campaign.
mandator)
Preliminary Partners send results of their respective work back to MaMa. This
results data is called “preliminary results”, as it requires processing and
(inbound, evaluation by MaMa before it can be marked as final. Process
from logs and partner status report are also transmitted to MaMa via
partner) this interface.
For example, MaMa will not disclose clients’ street address to call centers (they
usually get to know name, phone contact and sometimes one or two additional
attributes for verification purposes.)
On the other hand, print service providers usually don’t get to know the phone
numbers of clients, as the latter is not required to deliver printed letters via postal
services.
The diagram below contains a more formal version of the context diagram. It
includes an admin interface, which was left out in the informal version above.
MaMa Generic Business Context (informal)
The admin interface enables MaMa and campaign administrators to perform all
required administrative tasks needed to init, configure and operate campaigns.
3.1.2 Specific Business Context: Mobile Phone Contract Modification
The following diagram details the example already shown in section 1.1.1.
The data flows are detailed (in excerpts!) in the following table:
Context Details for Mobile Phone Contract Modification Campaign
Neighbor
Exchanged Data Format
System
Client Master Data: Name, Address, Contact, Zip-compressed
Mandator Contract, Tariff. Once for every client in the CSV, via sftp
(inbound) campaign, second as response to clarification (mandator
requests. uploads)
Mandator
Clarification request —– “ —–
(outbound)
Print Zip-
Service Print Data: Name, Address, parts of contract compressed,
Provider and tariff. PGP-encrypted
(outbound) CSV via http
upload
… … …
MaMa instances are supposed to run distinct virtual machines (whereas certain8
mandators or campaigns require instances to be deployed on their own physical
hardware - which results in significantly higher campaign costs.)
Element Description
A distinct instance of MaMa, running a specific campaign
«Instance»
(connected to a single mandator and a number of campaign-
MaMa
specific partner organizations)
«Category»
For every MaMa instance there is one distinct mandator.
Mandator
«Category» For every MaMa instance there might be several different partner
Partner organizations, each one having a distinct communication channel.
«Instance» Every MaMa instance has its own database instance, usually
Database within the same virtual machine.
Here you just find the shorthand form of the architectural approaches to the most
important (quality) requirements, plus the links to the detailed description in
section 8 (crosscutting concepts).
Flexibility
Implement customized editor for
(Configurable Section 8.2
CSV/fix DSL as Eclipse plugin
CSV/fix formats)
Include
Treat images as special case, store
special case
images in filesystem instead of
Performance for image
database, create unique path/filename
(import/process persistence in
based upon cient-ID, include load-
250k images/24hrs) code
testing in automatic build, create test-
generator,
data generator
Section 8.1
III.5 Building Block View
Element Description
Import
Imports data from Partners or Mandator via external interfaces
Handler
Export
Exports data to Partners or Mandator via external interfaces
Handler
Campaign
Data Completely generated. Stores all client- and campaign data.
Management
Operations Monitors (and reports) all import and export processes plus
Monitoring database and application state.
Interfaces:
Interface (From-
Description
To)
Read all required configuration information to perform
getImportConfig imports, especially details about data structures (like csv
formats) and filter chains.
storeClient
Sends an imported instance of Client to
CampaignDataManagement to be either updated or inserted.
Quality of Service:
Details:
Interfaces:
getExportConfig
Methods to get export configurations for a specific
campaign.
getCampaignConfig
store/retrieveConfig
Calls DataManagement to store/retrieve configuration
data.
Quality of Service: (not documented)
MaMa Level 2
Contained Blackboxes:
Element Description
Receiver
Receives data from partners or mandators via the
ImportData port.
FileArchiver
Non-erasable archive where all imported files are kept
for auditability.
FileFilter
Various filter operations, like decrypt, unzip etc.
Explained in the filter concept in section 8
Validator
Checks files, records (collections of strings) and client
objects for validity.
Important Interfaces:
Not documented.
MaMa Level 3
Receiver (Whitebox)
Rationale: We have to admit that this structure just evolved out of a number of
prototypes. A more functional oriented design would most likely improve
understandability, but we never refactored the code into that direction due to
different priorities.
Contained Blackboxes:
Element Description
Components that listen for input of specific kinds, e.g.
Directory or
the DirectoryListener watches for new files to
WebService or Message
appear in certain directories, (configurable) either in a
- Listener
local or remote file system.
One of the major use cases is Import File, which can be from both mandator and
partner. Such files contain always contain Client related data in configurable
formats (CSV, fix-formats or XML).
Prerequisite: Data has been imported from external source, has been
successfully filtered (i.e. decrypted and decompressed). See previous section
(Import Raw).
The diagram below contains error handling. In good cases there will be no
errors. Calls to ImportErrorHandler are only executed if errors occur!
Due to the sensitive nature of data handled by the original MaMa system the owner required strict
nondisclosure in that aspect. Therefore we are not allowed to go into any detail of security.
Campaign
Workstation (standard PC running Java-enabled OS)
Configuration
used to configure campaigns.
Workstation
For every campaign operated by InDAC there will be a single dedicated virtual
machine containing a database instance and all required MaMa code (except the
graphical configuration UI).
The German government regulations for the eHealth card contained a very
specific process to generate the “Common Insurance ID” (CID) for persons: This
ID could only be generated by a single government entity (formerly the
GPFunds, “Deutsche Rentenanstalt”, since 2012 the ISTG).
One (or several) operator workstations (standard PC’s) will be used to configure
MaMa instances after they have been physically deployed on their respective
VMs.
MaMa uses a code generator to generate all (!!) required persistence code from a
UML entity model. The overall concept of this generation is depicted in the
following diagram. Generic and campaign-specific parts are stereotyped in this
diagram. The «campaign-specific» Data Management component is
automatically created and packaged by the build process.
Core
Domain «campaign- Handwritten code, some Hibernate stuff, some
Data specific» generic finder and repository methods.
Management
Specific
Domain «campaign- UML model enhancing the Core Domain Model.
Model specific»
Code
«generic» not shown in diagram.
Generator
Prerequisites:
Every MaMa instance will handle data related to individual people - called
clients in MaMa domain terminology.
All clients will have a small number of common attributes.
For all productive campaigns MaMa needs to handle an arbitrary number of
additional attributes.
Every mandator will add several campaign-specific attributes to the client,
and/or will add campaign specific types (like insurance-contract or mobile-
phone-contract)
Once configured prior to campaign start, these campaign specific data
structures will rarely change9
Element Description
Abstract class, representing a person plus corresponding contact
Client
information.
Specific campaign models always contain a (physical) copy of the complete core
domain. The abstract Client class always need to be subclassed, and might be 1:n
associated with additional classes.
Specific Comain Model (for hypothetic insurance campaign)
Alternatives
As explained in the runtime scenario “import raw”, every file read during import
from an external source needs to be transformed via configurable filters. We
most often have two kinds of filters, encryption and compression.
The names and required parameter settings for every filter is managed as part of
the activity configuration within a campaign.
Encryption filters
We urge mandators and partners to use crypto providers from the BouncyCastle
portfolio. Encryption and decryption filters need credentials or certificates as
part of their configuration.
Due to the sensitive nature of data handled by the original MaMa system the owner required strict
nondisclosure in that aspect. Therefore we are not allowed to go into any detail of security.
Compression filter
MaMa uses the open source rule engine Drools for definition, implementation
and execution of business rules. Rules are defined as text files, which is
interpreted at runtime by the rule engine. This enables modification and
maintenance of rules without recompilation and redeployment of the whole
system.
On the other hand, faulty rules can seriously hamper an active campaign –
therefore modification of business rules shall always be thoroughly tested!
Rules always have a simple “when <A> then <B>” format, where <A> and <B>
are Java expressions.
You find a complete reference and many examples of the rule language at Drools
documentation home.
III.9 Architecture Decisions
Flexibility Scenarios
ID Scenario
F1 New CSV import format shall be configurable at CCT within 2 hours.
ID Scenario
Import and fully process 250.000 scanned documents (including images)
within 24hrs. That’s an average processing rate of approximately 3
P1
complete documents per second. Import format will be a combination of
csv file plus images as single files.
P2 Import and fully process 100.000 records of csv file within 30 minutes
Security Scenarios
ID Scenario
Client and campaign data from one mandator shall never be accessible for
S1
another mandator.
In case campaigns involve financial data of clients (e.g. credit card, bank
S3 account or similar information), these have to be processed and managed
compliant to PCIDSS regulations.
III.11 Risks
Term Definition
Process step of campaign. For MaMa-CRM: either inbound,
Activity
outbound or internal.
Activity,
Send data to either a partner or mandator.
outbound
As such biking2 has been around since 2009 and in it’s current Java based form
since 2014. Defining production as full filling the primary goal it’s been in
production ever since.
The project is published under Apache License on GitHub, use it however you
like. Though I’ve been blogging regularly about this pet project, the
documentation in its current form was created after I met Gernot and Peter at an
awesome workshop in Munich.
IV.1 Introduction and Goals
What is biking2?
The main purpose of biking2 is keeping track of bicycles and their milages as
well as converting Garmin Training Center XML (tcx) files to standard GPS
Exchange Format (GPX) files and storing them in an accessible way.
Main features
The application must only handle exactly one user with write permissions.
Most bike aficionados have problems understanding the question “why more
than one bike?”, the system should be able to keep track of everything between 2
and 10 bikes for one user, storing 1 total milage per bike and month. All milages
per month, year and other metrics should be derived from this running total, so
that the user only need to look at his odometer and enter the value.
The images should be collected from Daily Fratze, the source are all images that
are tagged with “Radtour”. In addition the user should be able to provide an
“unlimited” number of “gallery pictures” together with a date and a short
description.
1.2 Quality Goals
# Quality Motivation
The functional requirements are simple enough to allow a
simple, understandable solution that allows focus on
1 Understandability
learning about new Java 8 features, Spring Boot and
AngularJS.
1.3. Stakeholders
The following lists contains the most important personas for this application:
Role/Name Goal/Boundaries
Developers who want to learn about developing modern
Developers applications with Spring Boot and various frontends, preferable
using Java 8 in the backend.
Software Looking for an arc42 example; want to get ideas for their daily
Architects work.
Improving his skills; wants to blog about Spring Boot; looking for
Michael a topic he can eventually hold a talk about; needed a project to try
Simons out new Java 8 features.
IV.2 Constraints
The few constraints on this project are reflected in the final solution. This section
shows them and if applicable, their motivation.
Constraint Background
The application should be part of a Java 8 and
Spring Boot show case. The interface (i.e. the api)
Implementation in should be language and framework agnostic,
TC1
Java however. It should be possible that clients can be
implemented using various frameworks and
languages.
Third party
The interested developer or architect should be able
software must be
to check out the sources, compile and run the
available under an
application without problems compiling or
TC2 compatible open
installing dependencies. All external dependencies
source license and
should be available via the package manager of the
installable via a
operation system or at least through an installer.
package manager
Constraint Background
OS
The application should be compilable on all 3 mayor
TC3 independent
operation systems (Mac OS X, Linux and Windows)
development
Hardware Constraints
Constraint Background
Memory can be limited (due to availability on a shared host
Memory
TC5 or deployment to cloud based host). If deployed to a cloud
friendly
based solution, every megabyte of memory costs.
Constraint Background
OC1 Team Michael Simons
Configuration
Private git repository with a complete commit history and
and version
OC4 a public master branch pushed to GitHub and linked a
control /
project blog.
management
Published
under an The source, including documentation, should be
OC6
Open Source published as Open Source under the Apache 2 License.
license
2.3 Conventions
Conventions Background
Architecture Structure based on the english arc42-Template in version
C1
documentation 6.5
This chapter describes the environment and context of biking2: Who uses the
system and on which other system does biking2 depend.
Business Context
Biker
A passionate biker uses biking2 to manage his bikes, milages, tracks and also
visual memories (aka images) taken on tours etc. He also wants to embed his
tracks as interactive maps on other websites.
Daily Fratze
Daily Fratze provides a list of images tagged with certain topics. biking2 should
collect all images for a given user tagged with “Theme/Radtour”.
GPSBabel
GPSBabel is a command line utility for manipulating GPS related files in
various ways. biking2 uses it to convert TCX into GPX files. The heaving lifting
is done by GPSBabel and the resulting file will be managed by biking2.
Arbitrary websites
The user may want to embed (or brag with) tracks on arbitrary websites. He only
wants to paste a link to a track on a website that supports embedded content to
embed a map with the given track.
Technical Context
Backend (biking2::api)
The connection to Daily Fratze is http based RSS-feed. The feed is paginated
and provides all images with a given tag but older images may not be available
any more when the owner decided to add a digital expiry.
Furthermore biking2 provides an oEmbed interface for all tracks stored in the
system. Arbitrary websites supporting that protocol can request embeddable
content over http knowing only a link to the track without working on the track
or map apis themselves.
Collection of biking
RSS feed over Internet (http)
pictures
At the core of biking2 is a simple yet powerful domain model based on a few
entities of which a “Bike” and it’s “Milage” are the most important.
Although data centric, the application resigns from using too much SQL for
creating reports, summaries and such but tries to achieve that with new Java 8
features around streams, lambdas and map/reduce functions.
Building the application with Spring Boot is an obvious choice as one of the
main quality goals is learning about it. But furthermore using Spring Boot as a
“framework” for Spring Framework allows concentration on the business logic.
On the one hand there is no need to understand a complex XML configuration
and on the other hand all building blocks are still put together using dependency
injection.
Regarding dependency injection and testability: All injection should be done via
constructor injection, setter injection is only allowed when there’s no other
technical way. This hopefully prevents centralized “god classes” that control
pretty much every other aspect of the application.
Spring Boot applications can be packaged as single, “fat jar” files. Since Spring
Boot 1.3 those files contain a startup script and can be directly linked to
/etc/init.d on a standard Linux systems which serves TC4.
Interoperability will be achieved by using JSON over simple http protocol for
the main API. Security is not the main focus of this application. It should be
secure enough to prevent others from tempering with the data, confidentiality is
not a main concern (read: passwords can be transmitted in plain over http).
The internal single page application shall be implemented using AngularJS. The
deployable artifact will contain this application so there is no need for hosting a
second webserver for the static files.
For real time tracking the MQTT protocol will be used which is part of Apache
ActiveMQ, supported out of the box by Spring Messaging.
Graphing should not be implemented here but instead the Highcharts library
should be used. The configuration for all charts should be computed server side.
IV.5 Building Block View
The application packaged as biking2.jar contains two (the api and the spa) of
three main parts, as shown in the Business Context:
From those two we have a closer look at the api only. For details regarding the
structure of an AngularJS 1.2.x application, have a look at their developers
guide.
NOTE: To comply with the Java coding style guidelines, the modules
“bikingPictures” and “galleryPictures” reside in the Java packages
“bikingpictures” and “gallerypictures”.
5.1 Whitebox biking2::api
The following diagram shows the main building blocks of the system and their
interdependencies:
All components depend on a standard JPA EntityManager and some on local file
storage. I won’t go into detail for those blackboxes.
Contained blackboxes
Blackbox Purpose
bikes Managing bikes, adding monthly milages, computing statistics
(Blackbox) and generating charts.
locations MQTT and STOMP interface for creating new locations and
(Blackbox) providing them in real time on websockets via stomp.
galleryPictures
Uploading and managing arbitrary pictures
(Blackbox)
Interfaces
Interface Description
REST api containing methods for reading, adding and
bikes Api
decommissioning bikes and for adding milages to single bikes.
tracks Api REST api for uploading and reading TCX files.
Real time
MQTT interface to which MQTT compatible systems like
location
OwnTracks can offer location updates.
updates
RSS feed Needs an Daily Fratze OAuth token for accessing a RSS feed
reader containing biking pictures which are than grabbed from Daily
Fratze.
galleryPictures REST api for uploading and reading arbitrary image files
Api (pictures related to biking).
Intent/Responsibility
bikes provides the external API for reading, creating and manipulating bikes
and their milages as well as computing statistics and generating charts.
Interfaces
Interface Description
REST interface Contains all methods for manipulating bikes and
/api/bikes/* their milages.
Files
The bikes module and all of its dependencies are contained inside the Java
package ac.simons.biking2.bikes.
Intent/Responsibility
tracks manages file uploads (TCX files), converts them to GPX files and
computes their surrounding rectangle (envelope) using GPSBabel. It also
provides the oEmbed interface that resolves URLS to embeddable tracks.
Interfaces
Interface Description
REST interface Contains all methods for manipulating tracks.
/api/tracks/*
/api/oembed
Resolve track URLs to embeddable tracks
(content).
Files
The tracks module and all of its dependencies are contained inside the Java
package ac.simons.biking2.tracks.
Intent/Responsibility
trips manages distances that have been covered on single days without
relationships to bikes.
Interfaces
Interface Description
REST interface /api/trips/* Contains all methods for manipulating trips.
Files
The trips module and all of its dependencies are contained inside the Java
package ac.simons.biking2.trips.
Intent/Responsibility
locations stores locations with timestamps in near realtime and provides access
to locations for the last 30 minutes.
Interfaces
Interface Description
REST interface For retrieving all locations in the last 30
/api/locations/* minutes.
Files
The locations module and all of its dependencies are contained inside the Java
package ac.simons.biking2.tracker. The module is configured through the
class ac.simons.biking2.config.TrackerConfig.
Intent/Responsibility
bikingPictures is used for regularly checking a RSS feed from Daily Fratze
collecting new images and storing them locally. It also provides an API for
getting all collected images.
Interfaces
Interface Description
Provides access to the Daily Fratze RSS
RSS Feed reader
Feed.
Files
The bikingPictures module and all of its dependencies are contained inside the
Java package
ac.simons.biking2.bikingpictures.
Intent/Responsibility
Interfaces
Interface Description
REST interface Contains all methods for adding and reading
/api/galleryPictures/* arbitrary pictures.
Files
The galleryPictures module and all of its dependencies are contained inside
the Java package ac.simons.biking2.gallerypictures.
Contained blackboxes
Blackbox Purpose
Contains logic for generating configurations and definitions for
highcharts
Highcharts on the server side.
Blackbox Purpose
Generated JAXB classes for parsing GPX files. Used by the
gpx TracksController to retrieve the surrounding rectangle (envelope)
for new tracks.
Locations are stored and read via a Spring Data JPA based repository named
LocationRepository. This repository is only accessed through the
LocationService. The LocationService provides real time updates for
connected clients through a SimpMessagingTemplate and the
LocationController uses the service to provide access to all locations created
within the last 30 minutes.
New locations are created by the service either through a REST interface in form
of the LocationController or via a MessageListener on a MQTT channel.
Contained blackboxes
Blackbox Purpose
Generated JAXB classes for parsing RSS feeds. Used by the
rss
FetchBikingPicturesJob to read the contents of an RSS feed.
User interaction with biking2 and error handling is pretty basic and simple.
Deployment View
Node /
Description
artifact
biking2 Where biking2 development takes place, standard computer with
development JDK 8, Maven and GPSBabel installed.
Domain Models
Entities in biking2
Tables
Name Description
Stores the bikes. Contains dates when the bike was bought
bikes and decomissioned, an optional link, color for the charts and
also an auditing column when a row was created.
Name Description
A bike was bought on a given date and can be
decommisioned. It has a color and an optional link to an
BikeEntity
arbitrary website. It may or may not have milages
recorded. It has some important functions.
Name Description
decommission Decommissions a bike on a given date.
Adds a new milage for a given date and returns it. The
addMilage
milage will only be added if the date is after the date the
last milage was added and if the amount is greater than
the last milage.
getPeriods
Gets all monthly periods in which milages have been
recorded.
getLastMilage
Gets the last milage recorded. In most cases the same as
getMilage.
Persistency
biking2 uses an H2 database for storing relational data and the file system for
binary image files and large ascii files (especially all GPS files).
During development and production the H2 database is retained and not in-
memory based. The location of this file is configured through the
biking2.database-file property and the default value during development is
./var/dev/db/biking-dev relative to the working directory of the VM.
All access to the database goes through JPA using Hibernate as provider. See the
Domain Models for all entities used in the application.
The JPA Entity Manager isn’t accessed directly but only through the facilities
offered by Spring Data JPA, that is through repositories only.
User Interface
The default user interface for biking2 which is packaged within the final artifact
is a Single Page Application written in JavaScript using Angular JS together
with a very default Bootstrap template.
For using the realtime location update interface, choose one of the many MQTT
clients out there.
Furthermore biking2 uses wro4j together with a small Spring Boot Starter to
optimize JavaScript and CSS web resources.
This model file is filtered by the Maven build, version placeholders will be
replaced and all resources, in webjars as well as inside the filesystem, will be
available as biking.css and biking.js.
Transaction Processing
biking2 relies on Spring Boot to create all necessary beans for handling local
transactions within the JPA EntityManager. biking2 does not support distributed
transactions.
Session Handling
biking2 only provides a stateless public API, there is no session handling.
Security
biking2 offers security for its API endpoints only via HTTP basic access
authentication and in case of the MQTT module with MQTTs default security
model. Security can be increased by running the application behind a SSL proxy
or configuring SSL support in the embedded Tomcat container.
For the kind of data managed here it’s an agreed tradeoff to keep the application
simple. See also Safety.
Safety
1. Bikes which have been decommissioned cannot be modified (i.e. they can
have no new milages): Checked in BikesController.
2. For each unique month only one milage can be added to a bike. Checked in
the BikeEntity.
3. A new milage must be greater than the last one. Also checked inside
BikeEntity.
Exception/Error Handling
Errors handling to inconsistent data (in regard to the data models constraint) as
well as failures to validation are mapped to HTTP errors. Those errors are
handled by the frontends controller code. Technical errors (hardware, database
etc.) are not handled and may lead to application failure or lost data.
Logging, Tracing
Spring Boot configures logging per default to standard out. The default
configuration isn’t change in that regard, so all framework logging (especially
Spring and Hiberate) go to standard out in standard format and can be grabbed or
ignored via OS specific means.
All business components use the Simple Logging Facade for Java (SLF4J). The
actual configuration of logging is configured through the means of Spring Boot.
No special implementation is included manually, instead biking2 depends
transitively on spring-boot-starter-logging.
The names of the logger corresponds with the package names of the classes
which instantiate loggers, so the modules are immediately recognizable in the
logs.
Configurability
Spring Boot offers a plethora of configuration options, those are just the main
options to configure Spring Boot and available starters: Common application
properties.
Internationalization
Migration
biking2 replaced a Ruby application based on the Sinatra framework. Data was
stored in a SQLite database which has been migrated by hand to the H2
database.
Testability
The project contains JUnit tests in the standard location of a Maven project. At
the time of writing those tests covers >95% of the code written. Tests must be
executed during build and should not be skipped.
Build-Management
The application can be build with Maven without external dependencies outside
Maven. gpsbabel must be on the path to run all tests, though.
IV.9 Architecture Decisions
Problem
Constraints
Conversion should handle TCX files with single tracks, laps and additional
points without problem
Focus for this project has been on developing a modern application backend
for an AngularJS SPA, not parsing GPX data
Assumptions
Using an external, non Java based tool makes it harder for people who just
want to try out this application
Although good documented, both file types can contain varieties for
informations (routes, tracks, waypoints) which makes it hard to parse
Considered Alternatives
biking2 uses GPSBabel for the heavy lifting of GPS related data. The project
contains a README stating that GPSBabel must be installed. GPSBabel can be
installed on Windows with an installer and on most Linux systems through the
official packet manager. Under OS X it is available via MacPorts or Homebrew.
Problem
biking2 needs to store “large” objects: Image data (biking and gallery pictures)
as well as track data.
Considered Alternatives
Decision
I opted for local file system because I didn’t want to put much effort into
evaluating cloud services. If biking2 should runnable in cloud based setup, one
has to create an abstraction over the local filesystem currently used.
IV.10 Quality Requirements
Quality tree
Testability / Coverage
By using JaCoCo during development and the build process ensure a code
coverage of at least 95%.
biking2 has been up and running for nearly 2 years now, the architecture contains
no known risk for my usage scenario.
Term Description
AngularJS is an open-source web application framework mainly
maintained by Google and by a community of individual
AngularJS
developers and corporations to address many of the challenges
encountered in developing single-page applications.
NetBeans is a free and open Source IDE that fits the pieces of
NetBeans
modern development together.
Spring Spring Data JPA, part of the larger Spring Data family, makes it
Data JPA easy to easily implement JPA based repositories.
Software developers who plan to create a chess program of their own receive
valuable tips and learn about software architecture too.
V.1 Introduction and Goals
This section introduces the task and outlines the objectives pursued by
DokChess.
What is DokChess?
Essential Features
The following table describes the key quality objectives of DokChess. The order
of the goals gives you a rough idea of their importance.
Using existing
DokChess can be integrated in existing graphical chess
frontends
frontends with reasonable effort.
(Interoperability)
Acceptable playing
DokChess plays strong enough to beat weak opponents
strength
safely and at least challenges casual players.
(Attractiveness)
Quick response to
Since DokChess is used as live-demo in seminars and
opponent’s moves
lectures, calculation of moves takes place quickly.
(Efficiency)
The quality scenarios in section V.10 detail these goals and serve to evaluate
their achievement.
1.3 Stakeholders
The following table illustrates the stakeholders of DokChess and their respective
intentions.
At the beginning of the project various constraints had to be respected within the
design of DokChess. They still affect the solution. This section represents these
restrictions and explains – where necessary – their motivations.
Configuration
At the beginning (Version 1.0) Subversion at SourceForge, later
and version
Git at GitHub.
management
Test tools and JUnit 4 with annotation style both for correctness and
test processes integration testing and for compliance with efficiency targets.
2.3 Conventions
Coding
Java coding conventions of Sun / Oracle, checked using
guidelines for
CheckStyle
Java
This section describes the environment of DokChess. Who are its users, and with
which other systems does it interact with.
Actor Description
Chess is played between two opponents, who move their pieces in
Human
turn. DokChess takes the role of one of the opponents, and
opponent
competes against a human opponent. For this purpose, the two need
(user)
to communicate, e.g. about their moves, or draw offers.
Computer
As an alternative to a human opponent DokChess can also compete
opponent
with a different engine. The requirements related to the exchange of
(external
information are the same.
system)
If just a very few pieces are left on the board (e.g. only the two
kings and a queen), endgame libraries can be used analogously to
opening libraries. For any position with this piece constellation
Endgames these libraries include the statement whether a position is won,
(external drawn or lost, and if possible the necessary winning move. Within
system) DokChess no such library is created. Optionally an external system
is connected instead in order to bring clearly won games home
safely, or to use the knowledge from the libraries for analysis and
position evaluation.
3.2 Technical Context
Actor Description
A human player is connected to DokChess with a graphical front-
XBoard
end. The development of such is not part of DokChess. Each
client
graphical frontend can be used instead, if it supports the so-called
(external
XBoard protocol. These include Xboard (or Winboard on Windows),
system)
Arena and Aquarium.
Polyglot
Opening Polyglot Opening Book is a binary file format for opening libraries.
Book DokChess allows the optional connection of such books. Only read
(external access is used.
system)
On endgames
The following table contrasts the quality goals of DokChess (→ V.1.2) with
matching architecture approaches and thus provides easy access to the solution.
Platform appealing to
experiments • widely spread programming language Java → (a)
(Changeability)
• Interfaces for core abstractions (for instance:
position evaluation, game rules)
• immutable objects (position, move, … ) make
implementation of many algorithms easier
• “plugging” of elements with dependency
injection leads to interchangeability → (b)
• High test coverage as a safety net
Acceptable playing
• Integration of chess opening book libraries → (d)
strength (Attractiveness)
• implementation of minimax algorithm and a
proper position evaluation → (e)
• Integration tests with chess problems for tactics
and mate positions
Quick response to
opponent’s moves • Reactive extensions for concurrent calculation
(Efficiency) with newly found better moves as events → (f)
Small letters in brackets, e.g. (x), link individual approaches from the right hand
of the table to the following architectural overview diagram.
The remaining section V.4 introduces significant architectural aspects and refers
to further information in chapter V.
The interaction between algorithms takes place using the exchange of data
structures motivated by the domain implemented as Java classes (piece, move
and so on → Concept V.8.2 “Chess Domain Model”). Here, better
understandability is preferred at the cost of efficiency. Nevertheless, DokChess
reached an acceptable playing strength, as a run through the corresponding
scenarios shows (→ V.10 “Quality Scenarios”).
The key element of the data structure design is the game situation. This includes
the placement of the chess pieces and other aspects that belong to the position
(such as which side moves next). Again readability is preferred to efficiency in
the implementation of the class motivated by the domain. An important aspect is
that, like all other domain classes this class is immutable (→ decision V.9.2 “Are
position objects changeable or not?”).
For the integration of opening libraries, the “Polyglot Opening Book” file format
was implemented (→ Building Block View V.5.1.4 “Subsystem Opening
(Blackbox)”). This way, DokChess responds with profound chess knowledge in
the beginning of a game.
The classic minimax algorithm with a fixed search depth in the game tree is
responsible for the strategy as the game continues. Its basic implementation is
single-threaded. The evaluation of a position at an end node in the game tree is
based solely on the material (→ Building Block View level 2, V.5.2 “Engine
(Whitebox)”). Nevertheless, these simple implementations already meet the
quality scenarios under the given constraints.
An alpha-beta pruning illustrates the simple replacement of algorithms. Playing
strength and efficiency considerably improve by searching the tree more deeply
within the same computation time. The immutable data structures of DokChess
also facilitate implementing concurrent algorithms; a parallel minimax algorithm
is included as an example.
This section describes the decomposition of DokChess into modules. These are
also reflected in the package structure of the Java source code. In DokChess we
call modules of the first decomposition level subsystems. The building block
view level 1 presents them including their interfaces. For the subsystem Engine
this overview also includes a more detailed breakdown into level 2 (→ V.5.2).
Section V.6.1 (“Move Determination Walkthrough”) contains an example of the
interaction between the subsystems at runtime.
Intent/Responsibility
Interfaces
Files
Open Issues
Time control
Permanent brain (thinking while the opponent thinks)
Draw-offers and giving up of the opponent
Chess variants (alternative rules, such as Chess960)
Intent/Responsibility
This subsystem accounts for the rules of chess according to the International
Chess Federation (FIDE). It determines all valid moves for a position and
decides whether it is a check, a checkmate or a stalemate.
Interfaces
Interface ChessRules
Returns the set of all legal moves for a given position. The
current player is determined from the position parameter.
getLegalMoves
In case of a mate or stalemate an empty collection is the
result. Thus the method never returns null.
Concept V.8.2 “Chess Domain Model” describes the types used in the interface
as call and return parameters (Move, Position, Colour). Refer to the source code
documentation (javadoc) for more details.
Files
Open Issues
Apart from the stalemate, the subsystem can not recognize any draw. In
particular, the following rules are not implemented (→ V.11.2 “Risk:
Implementation effort too high”):
50 moves rule
Threefold repetition
Intent/Responsibility
This subsystem contains the determination of a next move starting from a game
position. The position is given from outside. The engine itself is stateful and
always plays one game at the same time. The default implementation needs an
implementation of the game rules to work. An opening library, however, is
optional.
Interfaces
The Engine subsystem provides its functionality via the Java interface
org.dokchess.engine.Engine.
Concept V.8.2 (“Chess domain model”) describes the types used in the interface
as call and return parameters (Move, Position). Refer to the source code
documentation (javadoc) for more information. You find details of the Engine
subsystem implementation in the white box view in section V.5.2 of this
overview.
Files
The implementation of the Engine subsystem and corresponding unit tests are
located below the packages
org.dokchess.engine...`
Intent/Responsibility
This subsystem provides opening libraries and implements the Polyglot opening
book format. This format is currently the only one available, which is not
proprietary. Corresponding book files and associated tools are freely available on
the Internet.
Interfaces
The Opening subsystem provides its functionality via the Java interface
org.dokchess.opening.OpeningLibrary.
The PolyglotOpeningBook class is an adapter for the Polyglot opening book file
format. Implementation of OpeningLibrary that reads a binary file in the
appropriate format and returns a move to the specified position, if the library
contains any.
Concept V.8.2 “Chess Domain Model” describes the types used in the interface
as call and return parameters (Move, Position). Refer to the source code
documentation (javadoc) for more information.
Files
The implementation, unit tests and test data for the Polyglot file format are
located below the packages
org.dokchess.opening...
Open Issues
The implemented options for a move selection from the Polyglot opening
book in case of several candidates are limited (the first, the most often
played, by chance).
The implementation can not handle multiple library files at the same time.
It can therefore not mix them to combine the knowledge.
Intent/Responsibility
The module determines the optimal move for a position under certain conditions.
In the game of chess an optimal move always exists, theoretically. The high
number of possible moves and the resulting incredible mass of game situations
to consider makes it impossible to determine it in practice. Common algorithms
like the Minimax therefore explore the “game tree” only up to a certain depth.
Interfaces
The module provides its functionality via the Java interface
org.dokchess.engine.search.Search.
Files
Intent/Responsibility
Interfaces
The Evaluation module provides its functionality via the Java interface
org.dokchess.engine.eval.Evaluation.
The class org.dokchess.engine.eval.StandardMaterialEvaluation is a very
simple implementation. The interface contains constants for typical ratings.
Files
Open Issues
In the pure material evaluation it does not matter where the pieces stand. A pawn
in starting position is worth as much as one short before promotion. And a
knight on the edge corresponds to a knight in the center. There is plenty of room
for improvement, which has not been exploited because DokChess should invite
others to experiment.
V.6 Runtime View
In contrast to the static building block view, this section visualizes dynamic
aspects. How do the pieces play together?
After establishing the XBoard protocol, the client (white) starts a game by
indicating a move. The following sequence diagram shows an example
interaction at the subsystem level from the input “e2e4” (white pawn e2-e4) to
DokChess’ response, which is the output “move b8c6” (black knight b8-c6,
“Nimzowitsch defense”).
Sample interaction for move determination
First, the Text UI subsystem validates the input with the aid of the Rules
subsystem (→ Concept V.8.4 “Plausibility Checks and Validation”). The move in
the example is recognized as legal and performed on the (stateful) Engine (the
performMove message) afterward. Then, the Text UI subsystem asks the engine
to determine its move. Since move computation can take a long time, but
DokChess should still continue to react to inputs, this call is asynchronous. The
engine comes back with possible moves.
The Engine examines at first whether the opening book has something to offer.
In the example, this is not the case. The engine has to calculate the move on its
own. It then accesses the Rules and determines all valid moves as candidates.
Afterward, it investigates and rates them, and gradually reports better moves
(better from the perspective of the engine) back to the caller (the Text UI
subsystem). Here, the observer pattern is used (implementation with reactive
extensions).
The example diagram shows that two moves have been found (pawn e7-e5,
knight b8-c6) and finally the message, that the search is complete, so the engine
does not provide better moves. The Text UI subsystem takes the last move of the
Engine and prints it as a string to standard output according to the XBoard
protocol: “move b8c6”.
V.7 Deployment View
Within Arena, the script file is declared in the following menu “Engine | Install a
new Engine …”. You will see a file selection, the file type can be limited to *
.bat files. Then, set the engine type to “Winboard”. In other chess frontends,
declaring an engine is very similar See corresponding documentation for details.
V.8 Cross-cutting Concepts
DokChess abstains from the use of a concrete DI framework. The modules are
hard-wired in the code, however only in unit tests and glue code (for example,
the main class). No annotation driven configuration is present in the code.
“The game of chess is played between two opponents who move their pieces
on a square board called a ‘chessboard’.”
This section contains a brief overview of these data structures and their
relationships. All the classes and enumeration types (enums) are located in the
org.dokchess.domain package. See the source documentation (javadoc) for
details.
A chess piece is characterized by colour (black or white) and type (king, queen,
and so on). In the DokChess domain model, a piece does not know its location
on the board. The Piece class is immutable, and so are all other domain classes.
The Position class describes the current situation on the board. In particular,
these are the piece locations on the board, which are internally represented as a
two-dimensional array (8 x 8). If a square is not occupied, null is stored in the
array. To complete the game situation, the Position class includes information
about which side moves next, which castlings are still possible (if any), and
whether capturing en passant is allowed.
DokChess itself has no graphical user interface. It interacts via the XBoard
protocol with the outside world (→ decision V.9.1 “How does the engine
communicate with the outside world?”).
The XBoard protocol is text-based. If you have mastered the main commands
(see Figure …) starting DokChess in a command line (Unix shell, Windows
command prompt, …) enables you to interact with the engine. The table below
shows a sample dialog, all commands are terminated with a new line). By
default the engine plays black. You can change this with the “white” command
of XBoard.
Client → DokChess
Comments
DokChess → Client
client wants to use the XBoard-Protocol
xboard (required since engines partly understand
other, sometimes even multiple protocols)
(new line)
protover 2 protocol version 2
feature line by line notification of additional features
done=1 of the engine (here: none)
e2e4 white plays pawn e2-e42
move
black (DokChess) plays knight b8-c6
b8c6
quit client ends the game (DokChess terminates)
A more typical use of DokChess is a graphical chess frontend like Arena (see
image below). It accepts the moves of the opponent in a comfortable interface,
passes them to DokChess in the form of XBoard commands like in the table
above (column “Client → DokChess”) and translates the answers (column
“DokChess → Client”) graphically.
the XBoard protocol for interactive user input from the opponent
opening libraries in the form of files
Input that comes through the XBoard protocol is parsed from the corresponding
subsystem. In case of unknown or unimplemented commands DokChess reports
the XBoard command “Error” back to the client.
In case of move commands DokChess checks using the rules subsystem whether
the move is allowed or not. In case of illegal moves DokChess reports the
XBoard command “Illegal move” back to the client. When using a graphical
front end, this case should not occur, since these typically accept only valid
moves. The case is likely relevant when interacting via command line (→
Concept V.8.3 “User Interface”).
Inputs that come through the XBoard protocol are parsed from the corresponding
subsystem. For unknown or unimplemented commands DokChess reports the
XBoard command “Error” back to the client. When setting up a position
DokChess checks the compliance with the protocol, but not whether the position
is permitted. In extreme cases (e.g. if no kings are present on the board), the
engine subsystem may raise an error during the game.
For opening libraries DokChess only checks whether it can open and read the
file. In case of a failure (e.g. file not found) it raises an exception (→ Concept
V.8.5 “Exception and Error Handling”). While reading the file the opening
subsystem responds with a runtime error to recognized problems (for example,
invalid file format). However, the content of the library itself is not checked. For
example, if invalid moves are stored for a position it is not recognized. The user
is responsible for the quality of the library (see → V.3.1 “Business Context”). In
extreme cases, the engine may respond with an illegal move.
DokChess has no own user interface. Therefore it must indicate problems to the
outside world.
The javadoc of methods and constructors in question shows the rare cases where
exceptions are expected in DokChess. Trouble reading an opening book file, or
when trying move calculation within the engine at an invalid position (if
identified). All other exceptions would be programming errors (please report
them under https://github.com/DokChess/).
The XBoard subsystem catches all exceptions and communicates them via the
XBoard protocol outwards (command “tellusererror”). A graphical front-end
usually visualizes them in an error dialog or alert box. The image below depicts
that for the chess frontend Arena.
The DokChess functionality itself can be checked easily with unit tests. This is
particularly true for the correct implementation of the game rules and for the
game play of the engine (→ Concept V.8.7 “Testability”). It holds true for your
own extensions in this area as well.
For the communication between the client and DokChess via the XBoard
protocol – in addition to interactive operation via a shell (→ Concept V.8.3
“User Interface”) – the client may monitor the conversation. Common chess
frontends permit this by writing log files and/or a simultaneous display of a log
window during the game. The image below shows this functionality within
Arena.
Log and debug window for XBoard Protocol in Arena
If the engine blocks and it is unclear what went on on the XBoard protocol such
tools are simply invaluable. Due to the availability of this feature a
communication protocol tracing was not implemented within DokChess at all.
8.7 Testability
Standard unit testing, which examine the individual classes, are named as the
class itself with suffix Test . In addition, there are tests that examine the
interaction of modules, and in extreme cases the whole system. With the help of
such tests, the correct playing of DokChess is checked. More complex, long-
running integration tests are below src/integTest. This includes playing entire
games.
In many tests positions must be provided as call parameters. Here the Forsyth-
Edwards Notation (FEN in short) is used. This notation allows the specification
of a complete game situation as a compact string without a line break and is
therefore perfect for use in automated tests.
Lowercase letters stand for black, uppercase for white pieces. For the piece types
the English names (r for rook, p for pawn …) are used.
Sample position
The game situation in the picture above with white before the 79th move, with
30 half-moves long no piece was captured and no pawn was moved, looks like
this in FEN
1 "6r1/6pp/7r/1B5K/1P3k2/N7/3R4/8 w - - 30 79"
and reads “6 squares free, black rook, square free, new rank …”.
Details about the notation can be found for example at Wikipedia. The Position
class has a constructor that accepts a string in FEN. The toString method of this
class also provides FEN.
V.9 Architecture Decisions
9.1 How Does the Engine Communicate with the Outside World?
Problem Background
A whole series of graphical user interfaces are available for playing against chess
programs. Moreover, there are software solutions with a larger scope for chess
enthusiasts. In addition to the game “Human vs. Machine”, they offer more
functionality, such as analyzing games. Over time, new chess programs will be
released – and others will possibly disappear from the market.
Depending on how the connection with such programs is realized, DokChess can
or can not communicate with specific frontend clients. Thus, the issue affects
DokChess’ interoperability with existing chess software and its adaptability to
future chess software.
Constraints
Assumptions
Considered Alternatives
Neither of the two protocols are formally specified, but both are publicly
documented.
Both protocols are text-based, and communication between the frontend and the
engine is via stdin/stdout. In both cases the front end starts the engine in a
separate process.
Under the given constraints, the quality goals can generally be achieved with
both options. Depending on which protocol is implemented, different front ends
are supported.
The decision in favor of the XBoard protocol was made in early 2011. The
structure of DokChess allows us to add alternative communication protocols
(UCI or other) without having to change the engine itself for this, see
dependencies in the building block view (→ V.5.1 “Building Block View, Level
1”).
The preferred front end for Windows is Arena. It is freely available and tops the
functionality of WinBoard. It has good debugging facilities. For example, it can
present the communication between the frontend and the engine live in a
window (→ screenshot in V.8). Arena supports both protocols.
By opting for the XBoard protocol, other operating systems (in addition to
Windows, especially Mac OS X and Linux) are also supported with freely
available frontends (see the preceding table). As such, a larger circle of
interested developers may use the engine, which was finally essential.
Problem Background
For various DokChess modules, game situations on the chess board (so-called
positions) must be provided and exchanged between them. Do we make the
associated data structure changeable or unchangeable (immutable)?
During a game, the position changes when the opposing players move their
pieces. In addition, the engine performs possible moves in its analysis, tries to
counter the moves of the opponent, evaluates the outcoming positions, and then
discards moves. The result is a tree that contains many thousands of different
positions, depending on the search depth.
Constraints
Affected Risks
Assumptions
Considered Alternatives
The starting point is domain-driven classes for square, piece and move (→
Concept V.8.2 “Chess Domain Model”). These classes are realized immutable as
value objects (the e4 field always remains e4 after it’s construction).
The following table summarizes the strengths and weaknesses of the two
options, they are explained below.
(2)
. (1) changeable
unchangeable
Implementation effort (-) higher (+) lower
Efficiency (memory (+) more (-) higher
consumption) economical demand
Efficiency (time behaviour) (o) neutral (-) worse
Suitability for concurrent
(-) bad (+) good
algorithms
The position with its extensive state is not copied in each move. This saves
memory and CPU time, and it treats the garbage collector with care. For analysis
algorithms, however, it is necessary to implement functionality that takes back
the effect of moves (“undo”). This Undo also takes time, hence the neutral rating
(o) for the time behavior.
(-) Negative Arguments
When you perform a move, the position is copied. It does not change the
original. This eliminates the implementation of move reversal (Undo). Clients
can simply store the old position as a value. This saves effort in the
implementation compared to option (1).
Copying the state for each new position takes time. When analyzing situations, it
covers many positions, which can take a lot of time.
Beyond that, copying the state for each new position costs memory. The
implementation of search algorithms with backtracking at least prevents
complete game trees from ending up on the heap. Nevertheless, more memory is
required, and the garbage collector has more work to do.
Decision
The decision for the unchangeable position (option 2) was made in early 2011
due to the advantages in terms of ease of implementation and the prospect of
exploiting concurrency. All the disadvantages of option 2 are related to
efficiency.
Due to the risk of failing to achieve the objectives with respect to the playing
strength in an acceptable computing time (attractiveness, efficiency), prototypes
of both versions have been implemented and compared in a mate search
(Checkmate in three moves) with the minimax algorithm. With option 2, the
search took 30% longer, assuming you implement copying efficiently. But this
option met the constraints still well.
The quality scenarios in this section depict the fundamental quality goals of
DokChess (→ V.1.2) as well as other required quality properties. They allow the
evaluation of decision alternatives.
The following diagram gives an overview of the relevant quality attributes and
their associated scenarios (→ table in V.10.2). The quality goals are also
included in the figure, and each refers to the scenarios that illustrate them.
The initial letters of the identifiers (IDs) of the scenarios in the following table
each stand for the parent quality attribute (in German), E for efficiency, for
instance. These identifiers are also used in the utility tree (→ V.10.1). The
scenarios cannot always be clearly assigned to one characteristic. Therefore, they
sometimes appear several times in the utility tree.
No. Scenario
A person with basic knowledge of UML and chess looks for an
W01 introduction to the DokChess architecture. He or she gets the idea of the
solution strategy and the essential design within 15 minutes.
Within a chess match, a knight fork to gain the queen or a rook arises for
F03 the engine. The engine gains the queen (or the rook) in exchange for the
knight.
Within a chess match, a mate in two unfolds to the engine. The engine
F04
moves safely to win the game.
During the game, the engine responds to the move of the opponent with
E01
its own move within 5 seconds.
During the game, the engine receives an invalid move. The engine rejects
Z01 this move and allows the input of another move thereafter and plays on
in an error-free way.
The engine receives an illegal position to start the game. The behavior of
Z02 the engine is undefined, cancelling of the game is allowed, as well as
invalid moves.
The following risks have been identified at the beginning of the project. They
influenced the planning of the first three iterations significantly. Since the
completion of the third iteration the risks are mastered. This architectural
overview shows the risks, including the former eventuality planning, because of
their large impact on the solution.
If it is not possible to make a working connection, the solution can not be used
with existing frontends. This not only lacks an important feature (→ V.1.1
“Requirements Overview”), but also makes the solution as a whole, especially as
a case study, untrustworthy.
Contingency Planning
Risk Mitigation
Contingency Planning
Risk Mitigation
In order to reduce effort, the following rules are not implemented at first:
50 moves rule
threefold repetition
Their absence has little consequence with respect to the playing strength, and
consequence no consequence with respect to the correctness of the engine.
Connecting opening libraries and endgame databases has low priority and and
takes a back seat at first.
The quality goals demand both an acceptable playing strength and a simple,
accessible solution. In addition, there are requirements with respect to efficiency.
It is uncertain whether the planned Java solution with an object-oriented domain
model and simple move selection can achieve these competing goals.
Contingency Planning
In conference talks, parts of the live demonstration could be omitted. If
necessary, we could show games played before.
Risk Mitigation
“The game of chess is played between two opponents who move their pieces
on a square board called a ‘chessboard’.”
The following glossary contains English chess terms and terms from the world
of computer chess. Some of them go beyond the vocabulary of infrequent or
casual chess players.
See FIDE Laws of Chess or the Wikipedia glossary of chess for more
information.
Chessboard
Chess Terms
Term Definition
A rule in chess, which states that a player can claim a draw after 50
50 move
moves whilst in the meantime no pawn has been moved and no
rule
piece has been taken.
A special move in chess where both the players’s king and one the
Castling
rooks are moved. For castling, different conditions must be met.
A chess game which ends with no winner. There are various ways
Draw
to end it with a draw, one of them is stalemate.
Single action (move) of an individual player, unlike the sequence of
Half-
a white and a black move which is counted as a move e.g. when
move
numbering.
Polyglot
Binary file format for opening libraries. Unlike many other formats
Opening
for this purpose the documentation of it is freely accessible.
Book
End of a chess game in which the player to move does not have a
Stalemate valid move, but his or her king is not under attack. The game is
considered a draw.
Threefold A rule in chess, which states that a player can claim a draw if the
repetition same position occurs at least three times.
WinBoard
See XBoard protocol.
protocol
While working with AsciiDoc, I came up with several other little scripted tasks,
which helped me in my workflow. These were added to the original arc42-
generator and turned it into what I now call docToolchain.
https://doctoolchain.github.io/docToolchain/
VI.1 Introduction and Goals
The need to deliver an arc42 solution architecture in different formats was the
primary driver which gave birth to docToolchain. As a technical person, I saw
the value of text-based documentation. However, other stakeholders wanted to
have the documentation
Soon after fulfilling these needs, I noticed that it is quite hard to update changing
UML diagrams. “Couldn’t this be automated?” I thought to myself and created
the exportEA-task as a simple Visual Basic script.
Together with Gernot Starke, I gave a talk about this approach, and I got
feedback from the audience like “… but I don’t use Enterprise Architect - can I
also use MS Visio?”.
“no, not at the moment. But docToolchain is not only a tool. I want it to be an
idea - a change in how you think. If EA can be easily automated, I am sure Visio
can be automated too!”
What I didn’t expect was, that a few days after this statement, we got a pull
request with the exportVisio-Task!
This way, docToolchain evolved through the requirements and imagination of its
users.
1.1 Problem Statement
You can apply the same approach to your documentation. This is called the
Docs-as-Code approach, e.g., you treat your documentation the same way as you
treat your code. To do so, you need several helper-scripts to automate repeating
tasks for building your documentation and it is a waste of time to set up these
tasks for each and every project from scratch.
The functional requirements are mainly split up into two different kinds of
functionality:
The project should run in different enterprise environments. It has to run with
different version control systems and without direct access to the internet (only
via proxies, e.g., for dependency resolution)
Documentation is not only crucial for open source projects but also essential for
enterprise projects. (Note: I also listed this as constraint C3)
RQ4 - OS independent
The toolchain should be available for the two major build systems, Maven and
Gradle.
This ensures that most JVM based projects can use it.
The project should be set up in such a way that it runs right after you’ve cloned
the repository.
This is to avoid the need for a special setup to be able to use it or change project
code.
Confidentiality
This quality goal is not docToolchain specific but regarding security very
important.
Because the system is not only targeted for open source environments but also
for enterprise ones, it has to be ensured that no data is sent to 3rd-party systems
without the user knowing it. For example, there are server-based text analysis
tools and libraries which send the text to be analyzed to a 3rd party server. Tools
and libraries like these must not be used.
Ease of Use
The docToolchain project is still a young open-source project and hence needs a
stable and growing user base. The easiest way to achieve this is to make
docToolchain extremely easy to use.
Maintainability
There is no big company behind docToolchain - only users who evolve it in their
spare time. So, a developer should be able to make most changes needed to
evolve docToolchain in a time-box of one to three hours.
1.3 Stakeholders
Contributors are mostly users of the system who need to fit a docToolchain task
to their needs or need an additional task.
General docToolchain users: These are mainly software architects and
technical writers with a development background. It is very likely that a
docToolchain user also uses arc42 and is familiar with it.
They also need to be able to create different output formats for different
stakeholders.
Users not working with the JVM: docToolchain also caught the attention of
users who do not primarily work on the JVM. These users need to use
docToolchain, just like any other command-line tool.
docToolchain has to run on all modern operating systems which users need for
development, e.g., Windows, Linux, macOS.
docToolchain is built for the JVM. While some of the features provided might
also work together with other environments, this can’t be guaranteed for all
tasks.
C3 - enterprise ready
C4 - headless
docToolchain has to run headless, e.g., without a display, to run on build servers.
This chapter describes the context for which docToolchain is designed and the
functional scope of it.
Business Context
Business Context
The above diagram is correct regarding the connections from docToolchain, but
abstracted regarding the relationships from the two actors “Contributor” and
“Reader”:
Those actors represent users who contribute to the documentation or access it.
The connections shown between those actors and the neighbor systems are
abstract because these users do not directly access the files. And they might use
different applications to read an modify the content.
docToolchain itself uses exactly the applications shown or reads and modifies
the files directly.
It creates the output documents directly as file content. Only for Confluence, the
Confluence API and thus Confluence as a System is used.
To read the input documents, docToolchain often needs an Application which
can be remote-controlled to convert and read the documents. But it directly reads
xlsx- and MarkDown-files.
The Actors represent roles. Each user can access the system through all of those
roles. Each user will likely have a primary role.
Actor /
Description
Neighbor
These are the users who use docToolchain to manage their
Technical documentation. They create the document structure and
Writer (user) configure the connection between different documentation
items mainly via include- and image-directives in AsciiDoc.
Jira (external Issue tracking system from which docToolchain may export
system) issues to be included in the documentation
Git-Repository
Version control system from which docToolchain may export
(external
change log information to be included in the documentation
system)
Sparx
Enterprise UML modeling tool from which docToolchain may export
Architect diagrams (as images) and element notes to be included in the
(external documentation
system)
MarkDown-
Document which may be transformed into AsciiDoc by
File (input
docToolchain to be included in the documentation
document)
your solution
architecture The main document which references all other parts of your
documentation documentation through include-statements. For a solution
(AsciiDoc- architecture, this document is derived from the arc42-template
document)
arc42 template
The template that helps you to structure the documentation of
(as AsciiDoc-
your solution architecture
document)
docToolchain
the system that is described here
(system)
Technical Context
This section describes the technical interfaces to the components listed above.
System Interface
Jira (external system) REST-API
Git-Repository (external
Shell execution of commands
system)
MarkDown-File (input
nl.jworks.markdown_to_asciidoc Java library
document)
This section explains the scope of docToolchain, e.g., what types of tasks
docToolchain is responsible for and also what it is not responsible for.
docToolchain:
This chapter describes the strategy how we approached problems in the past and
how we will approach them in the future.
The first docToolchain tasks evolved from stand-alone scripts which were
executed from the command-line. The next logical step was to include them in a
build system.
The original build.gradle soon grew into a huge single file. To make it more
modular, we split it up into so-called script-plugins. You extract tasks which
belong together in an extra .gradle file (for docToolchain you will find those in
the /scripts folder) and reference them from the main build.gradle:
1 apply from: `script/exportEA.gradle`
The solution strategy for individual tasks can be broken up into two main classes
of tasks.
Export Tasks
These are tasks which export diagrams and plain text from other tools. All tools
are different, so most of them need individual solution strategies.
These tools save their data often in a proprietary binary data format, which is not
easy to put under version control.
The solution strategy for export tasks is first to try and read the file format
directly to export the data. An excellent example of this is the exportExcel task,
which uses the Apache POI library to access the file directly. This solution
makes the task independent of MS Excel itself.
However, there are tools where the file format can’t be read directly, or the effort
is too high. In these cases, the solution strategy is to automate the tool itself. An
excellent example of this case is the exportEA task where the task starts
Enterprise Architect in an invisible, headless mode and exports all diagrams and
notes through the COM interface. The drawbacks are that this task only runs on
Windows systems. It can also be slow, and while Enterprise Architect is
invisible, it still claims the input focus so that you can’t work with the machine
during export. However, besides those drawbacks, the automation is still
valuable.
A third kind of tools from which docToolchain exports data are web-based tools
like Atlassian Jira. The obvious solution is to use the available REST-API to
export it. There is also a Java-API which wraps the REST-API, but the direct
REST-API is preferred.
Most export tasks are quite slow. At least so slow that you don’t want to run
them every time you generate your documentation. In addition, some of the
exports (like exportEA) don’t run on a Linux-based build server. Because of this,
the general strategy is to put the exported artifacts under version control. The
tasks create Special folders into which they place - among the exported data - a
README.adoc which warns the user that the files in the folder will be overwritten
with the next export.
Generate Tasks
These are tasks which generate different output formats from the sources.
For these tasks, the general solution strategy should be to implement them as
additional Asciidoctor backend (as reveal.js does for example) or at least as a
plugin (as the PDF plugin does for example). However, the effort to create an
Asciidoctor backend is, because of missing documentation, quite high.
5.1 Level 1
Component Description
This is the Gradle build system which is used for
Gradle docToolchain to orchestrate the documentation tasks. Details
can be found at https://gradle.org .
These are various tools which are used to create parts of your
system documentation. Popular examples are MS Word and
Documentation MS PowerPoint. docToolchain interfaces these tools directly
Tools instead reading the source files because there is no known
direct file API for these tools. See level 2: Documentation
Tools for details.
These are the tools from which docToolchain is able to export documentation
fragments. Each tool is interfaced by at least one export task through a specific
interface.
Component Description
Jira is the issue tracking system from Atlassian. The
exportJiraIssues task exports a list of issues for a given
Jira & JQL-Search. These issues are exported through the Jira
Server REST API. The result is stored as an AsciiDoc
exportJiraIssues
table to be included from the Documentation Master. More
documentation for this task can be found in the manual.
Utitlity Tasks
Building Block View - Level 2: Utility Tasks
These are tasks which might be helpful in certain situations but do not directly
belong to the scope of docToolchain
Component Description
Asciidoctor is very strict regarding the encoding. It needs
UTF-8 as file encoding. But sometimes a text editor or some
operation on your documentation file might change the
fixEncoding encoding. In this case, this task will help. It reads all
documentation files with the given or guessed encoding and
rewrites them in UTF-8. More documentation for this task
can be found in the manual.
This package contains all tasks which assemble your documentation to various
output files in different formats.
Component Description
Asciidoctor as rendering engine is at the heart of this
package. docToolchain uses Asciidoctor as Gradle
plugin which wraps the Ruby implementation with
jRuby. This is mostly transparent for the user, but it is
important in the enterprise context: all Asciidoctor
plugins also refer to their wrapped versions and not the
Asciidoctor
Ruby gems. This way, we avoid to reference the Ruby
gem repository as an external dependency for
docToolchain. Instead, all wrapped plugins are
referenced from the standard java repositories. More
details can be found at
https://asciidoctor.org/docs/asciidoctor-gradle-plugin/ .
The next diagram shows the details of all currently implemented tasks. It focuses
on the various input artifacts which are transformed through the Gradle tasks
which make up docToolchain. Each connection is either a Gradle task which
transforms the artifact or an AsciiDoc include-directive which references the
input artifacts from the main documentation and thus instructs Asciidoctor to
assemble the whole documentation.
Runtime View
VI.7 Deployment View
docToolchain is only used to generate documentation and thus is not deployed to a production
environment. However, depending on your requirements, you might want to deploy it not only to
your dev machine but also to a build server.
For this option, you clone the docToolchain repository to a location outside of
your project for which you want to write documentation. You then add the
<docToolchain home>/bin-folder to your PATH variable. Now you can use
docToolchain as command-line tool:
1 doctoolchain <docDir> <task>
This approach works quite well and independent of your project. However, it
violates RQ6 - clone, build, test, run for your project. Someone who clones your
project will also have to install docToolchain before he can work on the
documentation. Also, breaking changes in docToolchain are also likely to break
your build if you do not update docToolchain on all systems.
This approach is the currently preferred option. You add docToochain to your
project by adding it as a Git submodule.
1 git submodule add https://github.com/docToolchain/docToolchain.git
This line adds one additional folder to your project, containing the whole
docToolchain repository:
1 yourProject/
2 ├─ docToolchain/ <-- docToolchain as submodule
3 ├─ src/
4 │ ├─ docs <-- docs for yourProject
5 │ ├─ test <-- tests for yourProject
6 │ └─ java <-- sources of yourProject
7 ├─ ...
8 ├─ build.gradle <-- build of yourProject
9 ├─ ...
As you can see, this gives you a clean separation of your project and
docToolchain. The git submodule is just a pointer to the docToolchain repository
- not a copy. It points to a specific release. This approach ensures that whoever
clones your project, also gets the correct version of docToolchain.
If your project uses another build system like Maven, you can still use this
approach. You simply use Maven to build your code and Gradle to build your
documentation.
Last but not least, you can deploy docToolchain as command-line tool to a
docker container. This then can be used in various ways (for instance in a Gitlab
pipeline).
VI.8 Cross-cutting Concepts
Automated Testing
In an ideal world, we should have covered all code with unit tests. However,
currently, the smallest unit of docToolchain is a Gradle task. Because of the
dependencies to Gradle, we can’t easily test these tasks in isolation.
The current solution for automated tests is to use the gradleTestKit and Spock.
Through the gradleTestKit, Gradle will start another Gradle instance with its
own test configurations. The gradleTestKit ensures that all tasks can be
integration-tested in an automated way.
This chapter lists the important design decisions which have been made while
docToolchain evolved. They fulfill two tasks:
explain users and contributors who are new to the project, why things are
how they are
help to revise decisions whose basis has changed
Decision: docToolchain will always use the JRuby version because the needed
jar-files can be downloaded from the same repository as all the other java
dependencies.
Decision: The first approach isn’t easy to use, and the second even violates a
constraint. So it was decided to use visual basic as an automation tool. Since this
is the native interface for a COM-Object (which Enterprise Architect provides),
the amount of bugs in the interface is expected to be minimal. For a first POC, I
used Visual Basic together with Visual Studio. This setup provides intelli-sense
and code completion features and thus makes it easy to explore the API.
However, the final task uses Visual Basic Script, which is a little bit different and
doesn’t provide you code completion features.
Problem: I initially planned to support the two major build systems known to
me: Maven and Gradle. While Asciidoctor supports both build systems through
plugins, I soon noticed that even basic features like PlantUML and PDF
generation are hard to maintain for both systems. In addition, some features are
easy (for me) to implement through Gradle and harder to implement in Maven.
However, script plugins also have advantages. They make the code more
compact and easier to maintain because they consist of single files and are not
distributed over several classes. The tasks are often so small that we included
their source in the manual of docToolchain. When a user reads through the
manual, he sees at once how the tasks are implemented. The chances are good
that such a user turns into a contributor with this knowledge.
Decision: the pros of using script-plugins weigh currently more than the cons.
docToolchain has to be easy to maintain and extend (see RQ2 - easy to modify
and extend.
There is one exception to this rule: Some tasks - like the Pandoc tasks - are just
wrappers to other executables. A binary plugin could even help in this situation
by providing an automated download of the executable.
There are several plain text markup formats available like MarkDown,
RestructuredText, Latex, and AsciiDoc.
Decision: the most common options to use (deploy) docToolchain are the three
described in chapter 7 - Deployment View
DD6.1 Embedded
This was the first approach used, and we do not recommend it anymore. In this
approach, you use docToolchain itself as a base project, and add all code and
documentation to that base project.
As you can see, this was only a good idea in the beginning, when docToolchain
mainly consisted of an extended Asciidoctor build templates.
This approach is currently a theoretical option. It has never been used yet, but is
mentioned here for the sake of completeness.
you can reference these scripts as remote files in your project’s build.gradle-
file:
1 apply from: 'https://github.com/docToolchain/docToolchain/blob/b415bfb/\
2 scripts/exportExcel.gradle'
This line references an exact version of the file - so as long as you trust GitHub
and your connection to GitHub, this approach is safe and works for all self-
contained Tasks.
DD6.3 Gradle Binary-Plugins
See DD4: Binary Gradle Plugins for why this was not an option in the past.
For this option, the existing script plugins have to be converted binary plugins
for Gradle.
As a result, they can be referenced directly from your build.gradle file. Html
Sanity Check is an excellent example of this approach.
1 plugins {
2 id "org.aim42.htmlSanityCheck" version "1.0.0-RC-2"
3 }
We could turn docToolchain into a binary plugin which references all other
plugins as its dependency. Alternatively, we could turn docToolchain into a
collection of binary plugins, and a User of docToolchain would reference those
plugins he needs.
VI.10 Quality Requirements
QS1: Confidentiality
When you think of documentation, security is not the first thing which comes to
your mind, is it?
But when you automate some parts of your documentation, or even just include
remote sources, security comes into play.
It can even be that you use a plugin (like the asciidoctorj-screenshot plugin)
which lets you execute arbitrary code in the generation phase.
QS3: Repeatability
This rule ensures that it doesn’t matter if you move the source or the generated
output from stage to stage.
No task of docToolchain will remove content. Tasks (like the export-tasks) may
only add content. This rule is to ensure that all generated content contains the
same information.
However, some formats might not be able to display the same layout and text
style.
QS5: Performance
However, we should strive for better performance of the tasks whenever we see a
chance to optimize.
Currently, a single binary Gradle plugin is seen as the right solution to achieve
this quality goal, but it is not yet on the roadmap. (see also DD4: Binary Gradle
Plugins)
QS7: Maintainability
Many users with different needs use docToolchain. Those different needs are the
result of different environments and different tools in use.
The “easy to modify” quality goal is currently achieved through the scripting
character of the Gradle script-plugins. The source is referenced from the
documentation and easy to understand and thus easy to modify.
However, this is in contrast to the “Easy of Use” quality goal: script plugin vs.
binary plugin.
VI.11 Risks and Technical Debt
This chapter describes the risks which might occur when you use docToolchain
and how they are - from an architectural point of view - mitigated.
Description: A software system might live for several decades. During this time,
some parts of the toolchain might get outdated. For instance, a UML modeler for
instance for which you didn’t buy a new license.
In such a case, you might not be able to re-generate parts of your documentation.
Mitigation: The highest risk of this kind is attached to the proprietary tools from
which diagrams and texts are exported. docToolchain exports these artifacts not
to the /build folder but to the /src/docs folder by purpose:
if one of the tools gets outdated, you still have the exported data and hence
can still work with it.
in addition, the exported .png-images and plain text files are easier to
compare than the often binary source formats. This enables a better review
of the changes in your documentation.
Description: When you start to use docToolchain and thus implement the Docs-
as-Code approach, you risk that colleagues do not accept this “new” approach.
In our experience, this is a low risk. We’ve never seen people switch back to MS
Word from AsciiDoc. However, it might give users a good feeling to be able to.
Mitigation: You can convert your docs to several output formats like PDF, MS
Word and Confluence. This gives you not only a “fallback” when you reach a
point where you think that the Docs-as-Code approach doesn’t fit your
requirements, it also allows you to work together with colleagues who haven’t
transitioned to Docs-as-Code yet.
TR3: Git Submodules
Description: Git Submodules are great in theory. As soon as you use them, you
will notice that it needs a bit of practice.
if added via ssh protocol, users without ssh configured for their git account
can’t clone them
submodules easily get in a “detached head” state
at least git on windows has authentication problems with submodules (use
of pageant helps)
Mitigation:
Description: the project does not have good test coverage. The Travis checks
often break.
Term Definition
COM,
Component COM is an interface technology defined and implemented
Object as a standard by Microsoft. See also COM on Wikipedia
Model
EA,
A UML modeling tool by Sparx Systems. See EA on
Enterprise
Wikipedia
Architect
A Java-COM-Bridge. See
JACOB
https://sourceforge.net/projects/jacob-project/ for details
POC, Proof
Minimalistic code that proofs a certain idea
of Concept
Sparx,
Sparx The company behind Enterprise Architect
Systems
This is also the reason why the structure of this document differs slightly from
the one described in arc42. Especially the first chapter might seem redundant in
context of this book because it describes the overall structure. The idea behind
this chapter is to give the readers all the information they need to understand
which parts of the documentation are important for them. The last chapter is also
one that is not part of arc42 because it contains typical information teams use to
organize their daily work. It was added to show how to incorporate such things
in your overall documentation and link between architecture documentation and
team organization. Moreover, it contains actual links between different pages
because the whole document was written with the use of a wiki system in mind.
VII.1 About this document
It is safe to assume that new readers of the document will start with the first page of the
document. Thus we can use this page to provide the most important information and guide the
reader through the document. This approach is very important especially when using wiki
systems otherwise they can become very confusing.
This documentation describes all aspects that should and must be considered in
the development and maintenance of the FotoMaX device software. It uses the
arc42 template as a basic structure. According to this, the documentation is
divided into the following subsections, which can be read from top to bottom,
leading from an abstract and external problem view to a concrete internal
solution view.
This chapter contains basic information necessary to understand the product and
the business context in which it was created.
Quality Requirements
This chapter deviates from the official Arc42 structure in order to emphasize the importance of
the quality requirements. Normally, these would only appear much later in the document,
which makes sense if they are described in great detail. In this case, here are only a
comparatively small number of scenarios. All of these are very important and therefore brought
into focus by appearing very early in the document.
Constraints
This chapter describes the constraints and requirements that limit software
design, implementation or the development process.
In this chapter the system is delimited from its environment. In this way, user
rolses, external systems and the associated interactions as well as needed
interfaces are identified.
Solution Strategy
The structural design and its decomposition into building blocks of various
granularity is described in this chapter.
Runtime View
All dynamic relationships that are to be highlighted are described in the runtime
view chapter.
Deployment View
Crosscutting Concepts
Architectural Decisions
Fundamental decisions should not be made on the basis of a gut feeling, but as
empirically as possible. In this chapter, all the information that is decisive for
design decisions is collected.
We see risks as all the things that can have a negative impact on the project and
the software system if they are not handled appropriately. This chapter describes
all risks and technical liabilities together with their possible effects and
countermeasures, to make sure that they are not forgotten.
Glossary
The glossary summarizes all terms that may hinder the understanding of the
documentation.
Organizational Topics
This chapter is not part of ARC42 but was added to this documentation to show how teams can
organize their daily work next to the architecture documentation so that both information
sources are kept close togther. This allows to link between both documentations but also
ensures that both are also always present. This in turn ensures that the architecture
documentation is not perceived as something that exists somewhere somehow, but is an
important part of one’s own work.
This chapter contains information that does not relate directly to the software
architecture, but to the day-to-day collaboration in implementing the software.
This includes, the Definition of Ready and Definition of Done, but also
guidelines, checklists and things like vacation planning.
VII.2 Introduction and Goals
This chapter describes the key requirements and driving forces that must be
considered when implementing the software architecture and developing the
system.
About FotoMaX
FotoMax does not take care of the actual printing of the orders. It provides the
link between the companies that set up a sales unit in their stores and those that
do the actual printing of the photo products. Based on the chosen version of
FotoMax these could even be the same companies. The products are paid
directly in the respective store or via mobile payment solutions.
In the simplest case, printing takes place directly in the store (“FotoMaX
Standalone”) or can be forwarded to a print shop (“FotoMaX Connect”) to allow
a larger variety of products like cloths, coffee cups or posters.
Supermarkets
Drugstores
Hotels
…
Stakeholders
The following people represent a particular view of the system and should
therefore be consulted in fundamental decisions.
Please note that these persons and their contact details are purely fictional. Similarities to
existing companies or persons are therefore purely coincidental.
This chapter prioritizes the quality attributes of the software based on ISO 25010
and explains the associated decisions.
Prioritization
The prioritization of the quality attributes of the system was carried out with the
involvement of the stakeholders (→VII.2.2). It was initially executed for the
sales unit then modified later to incorporate the portal:
Legend:
Very
1 Compromises are only possible in absolute exceptional cases.
important
Quality Scenarios
The following scenarios specify how exactly the software system should behave
in certain situations and what compromises may be possible.
# Attribute Description
When a customer places an order, the system must
Functional
S1 round the final amount in a commercially correct
Correctness
manner.
This chapter describes the constraints and requirements that limit software
design, implementation or the development process.
Organizational Constraints
The company basically has two main products that are customized depending on
the business partner in terms of features, workflows and graphical assets
(→VII.5.1).
Start of
Wizard: 07.2010 Portal: 03.2018
development
Wizard
Approx. 250 in different versions
Installations
Technologies Used:
Wizard: .NET 4.8, C#, WPF
Portal: .NET 6, C#, Angular 11, NServiceBus for internal
communication between services
Runtime Environment:
Wizard: Windows 10, SQLite
Portal: Windows Server 2019, SQL Server 2019
Release Cycles:
Wizard: About once every two to six months, depending on the
partner, over the air.
Portal: Approx. every two weeks Technische Besonderheiten:
Note: 40 Wizard instances from before 2015 do not have a remote update
capabilities, and must be updated by a service engineer until 2025. After that, the
maintenance contracts expire, forcing the customer to upgrade to a remote-
enabled version.
Conventions
Code
The coding guidelines are located in VII.14.2.1.
Test
The testing guidelines are located in VII.14.2.2.
Review
The review guidelines are located in VII.14.2.3.
VII.5 System Scope and Context
In this chapter the system is delimited from its environment. This way user roles,
external systems and the associated interactions, as well as the necessary
interfaces are identified.
Business Context
The business context describes the external dependencies of the software system
from a domain-oriented perspective.
FotoMaX maps two different workflows: In standalone mode, all jobs are
processed on the client’s premises; in connected mode, jobs are forwarded to
external print service providers.
Designation Description
End A person who uses photo printing services via a sales unit and
Customer can track them via the portal.
Print An employee of the print provider who can view order data and
Provider modify orders.
Portal Customer and partner portal via which orders can be tracked.
Order The external system of the print provider to which print orders
System are forwarded. Each print provider can be expected to have its
Print own system.
Billing
The billing system of the printing site provider, via which print
System /
jobs are billed.
Printing Site
Standalone Setup
In standalone mode the sales unit is only connected to a local printer and has no
internet connection. All orders are processed and paid for within the premises of
the pitch provider. The supplier rents both the sales unit and the printer from
FotoMaX at a fixed monthly rate. In addition, consumables such as ink and
paper are billed according to usage. In addition to printing the ordered items, the
sales unit also prints a receipt, which has to be paid by the end customer at the
checkout of the pitch provider. FotoMaX is not involved in the actual billing
process.
Connected Setup
The connected setup allows end customers to place more extensive orders and
track them online. In addition, the orders are not executed exclusivly on the
premises of the provider’s premises, but also at a corresponding print provider
on additional products such as mugs, t-shirts or similiar articles. In a partially
connected setup, the billing is done by the pitch provider.
In a full connected setup, the orders are then either paid for by EC or credit card
at the device or the customer receives an invoice via e-mail. In this case, the
pitch provider is not involved in the billing of an order, but receives a fixed
monthly stand fee, and commission on all sales. They can view their earnings at
any time via the portal.
Technical Context
The technical context highlights the technical environment in which the software
system exists and the respective interfaces to external systems.
Element Description
Service An employee of FotoMaX GmbH, who performs maintenance
Technician work on sales units on site.
An employee of the respective sales pitch provider, who performs
minor maintenance work on sales units. This includes replenishing
Local printing paper and cartridges of the receipt printer or retrieving
Technician orders in standalone mode. The wizard’s UI is used to confirm all
maintenance tasks. Local technicians have no access to the sales
unit’s operating system.
End A person who uses photo printing services through a sales unit, or
Customer views order data on the customer management website.
The software that takes orders and initiates prints either locally or
Wizard
remotely.
Receipt A thermal printer used to print out receipts for orders that then
Printer have to be paid at a cash register.
Pitch An employee of the pitch provider who can view orders and check
provider invoices.
Print An employee of the print provider who can view and, if necessary,
provider change job status and orders.
This chapter explains both the associated base application and the migration
strategy, which describes how the previous monolith is transformed into a
modulith.
The Modulith
Basic Design
As a basis for the modulith, a framework application was created based on the
Prism Framework (→VII.11.4), which provides general features for central
services such as user administration, settings management, etc.
Module Design
Workflow Modules: These are central modules that map domain specific
processes and workflows. As a rule, they also have more complex user interfaces
that are implemented as a workflow within the wizard.
Service Modules:: These are modules that add specific functionality to the
workflow. These include, for example, assets of the respective customer such as
logos, color designs, etc.; but also include functions that can change depending
on the characteristics of the sales unit.
Module Integration
The kernel integrates the modules into the application during a bootstrapping
process. The modules can access central interfaces, and they have a root element
that is called by bootstrapper to control their initialization. Modules are strictly
prohibited from accessing the concrete implementation of either other modules
or any central services. Rather, they have to request all services via dependency
injection, using constructor injection, meaning that the service interfaces are
injected as parameters into the module constructors.
Migration Strategy
In 2019, the architecture of the Wizard had a highly coupled structure, with
neither functional nor technical layering. The following diagram depicts this
situation by using the same colors for components with the same responsibility,
while the different sizes and distributions to represent the unstructured nature of
the system.
To decompose the monolith, first the various responsibilities within the codebase
are assessed. Then a strategic decomposition is prepared, and a frame application
is created, that can incorporate the modules.
The structural design and its decomposition into building blocks of various
granularity is described in this chapter. It uses different detail levels to zoom in
from abstract structures into increasingly detailed and concrete elements.
The following illustration shows the internal components of the Wizard and their
interdependencies as well as their interaction with external interfaces. The latter
partly interact with other software, hardware or even the different user groups on
the basis of a graphical user interface.
infrastructure (gray),
logic (orange),
and hardware connection (purple).
All versions of the sales units used the same infrastructure components. The
logic components are provided with their actual functionality at runtime through
a configuration that is specific to the sales unit. The hardware connection in turn
decouples all other components from the possible printers and connection
options of the sales unit.
Application Frame
Provides the functionality of a frame application that combines all
other components at runtime. Also includes components for cross-
Purpose
cutting concerns such as settings management, logging, error
handling, inversion of control, user interaction, etc.
Workflow Management
Contains all features that are needed to read and change the machine
Purpose state, getting information about consumables and help with
calibration.
Image Handling
No external interfaces, since all work steps are called via the
Interfaces
workflow engine.
Order Management handles the actual ordering. This is done via the
Purpose portal in the connected case or via the local printers in the
standalone case.
Hardware Management
Hardware Management does not have its own UI. Since Hardware
Special
Management is primarily a collection of loose components, there is
Features
no white-box representation in this documentation.
Level 2 – White-Box View of the Subsystems
Name Responsibility
Workflow Contains all views that are dynamically integrated into the main
UI UI.
Local Takes over all processes that are necessary to execute a local print
Processing job. This also includes the issuing of a receipt.
Handles all processes that are necessary to have a print job
Remote
executed by a print partner. This also includes the issuing of a
Processing
receipt.
This part of the documentation has not been further elaborated as it does not add any value to
the actual purpose of the documentation.
This part of the documentation has not been further elaborated as it does not add any value to
the actual purpose of the documentation.
VII.8 Runtime View
All dynamic relationships that are to be highlighted are described in the runtime
view chapter.
Below is the sequence that is run through during program startup for each
module to initialize itself and its managed components.
Not every type has to be initialized by the module itself. This is only necessary
for module components which actually require a special initialization. The
component initialization should happen here if possible asynchronously around
the start not to hinder.
Like any other module, the Order Management is initialized during the program
start. Depending on whether the Wizard is operated in standalone or connected
mode, a different procedure for the order process has to be chosen. The
following image shows the processes, that have to be executed during the
initialization of the workflow module to load the correct components.
Note: The same document printer is always installed in the sales unit, therefore it
can be decided via the selection of a template whether a remote order or a local
order is to be issued.
VII.9 Deployment View
The deployment view clarifies the runtime environments in which the individual
components of the system are installed and executed.
For the sake of clarity, the above illustration only shows the production
environment in a simplified form. This does not contain virtualization
environments, development environment, staging environments, and fallback
servers. A detailed overview can be found in the Infrastructure documentation of
the IT department, which takes care of the operation.
Artifact Description
Executable file of the wizard, which is installed by
wizard.exe a service technician on a sales unit before delivery.
Updates are done by the service technician on site.
This chapter describes what “errors” are, and how they should be handled.
Types of “errors”
Different types of errors can occur within software, therefore not everything that
is commonly referred to as an error is also an error in the sense of software
development.
Exceptions are the common means of choice in .NET to indicate errors. They
have the advantage that they can be checked and logged using appropriate
analysis tools. In addition, they automatically contain various environmental
information such as a stack trace, the time of occurrence and others. The
disadvantage is that they are not necessarily known to the caller. Thus, they may
be overlooked, not handled and in the last instance close the entire application.
In addition, the information that exceptions contain is not necessarily helpful for
the user since it is very technical.
Not Exceptional
Exceptions are intended for exceptional situations, but how do you deal with
non-exceptional situations? A result object is provided for this purpose. This
contains both technical error descriptions and error descriptions that a user can
follow. The result object can therefore also be used to inform users about a
problem situation and, if necessary, to prompt them to take countermeasures.
In the following example, this is illustrated by first checking whether the correct
data has been transferred or not in the case of a division. If not, this is
communicated to the user so that they can correct their input if necessary.
1 public Result<float> Divide(int dividend; int divisor)
2 {
3 if(divisor == 0)
4 {
5 return Result.Failed<float>("The divisor was zero thus divisio\
6 n was not possible.", "Please change the input.");
7 }
8
9 return Result.Success<float>(dividend / divisor);
10 }
Handling Errors
There are several ways to handle errors. In the following section, we will briefly
discuss these to give you a better sense of what to think about in each case.
Ignore
If possible, error conditions should not occur in the first place. If an error is so
unlikely that concrete handling seems too costly, then it should at least be
logged. However, this should be discussed with the product owner and quality
assurance.
Retry
Based on the context, it can be quite helpful to simply try an action again if it
does not succeed instead of throwing an exception immediately. However, this
should be discussed with the product owner and quality assurance.
Logging
Logging is a very extensive topic and has therefore been moved to a separate
chapter (→VII.10.3).
User Interactions
It may happen that exceptions are not caught. In that case they end up in the final
exception handler. This logs the error and shuts down the application in a
structured way. Such errors should not occur in a production environment!
Logging
When searching for the causes of errors, it is very helpful to know how the
software behaves in its real environment. This is particularly important in the
context of the wizard, since the sales units represent closed systems that are
difficult to access from the outside. Remote debugging or similar are not
possible at the current time. The production logs are therefore the only way to
obtain information about the use and status of the sales unit.
The ILogger interface is used for logging in the portal and in the wizard. This is
provided centrally and can be requested by any class via its constructor.
Log Level
Error log entries indicate that something has happened that should
not have happened, without automatically affecting the stability of
Error
the software. The most common case for error logs are caught
exceptions that could be handled.
In addition to the log level and possible exceptions, the context in which the
information occurred and when the log was written must also be logged. The
more meaningful the logs, the easier it is to analyze them later.
Logged data must not allow any conclusions to be drawn about individuals,
including contact details. Furthermore, it is not permitted to write account details
or similar sensitive information in the log. In order to allow better traceability
through the different layers or services, a unique session ID is automatically
assigned to each order transaction, and this is automatically part of each log
message.
Domain Model
The domain model is a technical data model that helps both in the design of
interfaces and in the communication between the various project participants.
The following domain model describes the considerations in the context of the
business processes of the FotoMaX company.
The following domain model is highly simplified and serves the purpose of a practical training.
Therefore, it does not claim to be technically correct in its entirety. For example, large parts of
Customer Management and Partner Management are missing. The domain Operations will
only be found in this chapter and in no other, as it would have greatly complicated all other
examples.
Entity Description
Customer who initiates an order and provides images. Both
Costumer
activities can be done via a website, app or a sales unit.
End customer invoice that settles the amount due resulting from
Invoice an order. In the standalone case there is no connection to the
customer.
Incoming
An invoice issued by a partner and to be paid by FotoMaX.
Invoice
Outgoing
An invoice issued by FotoMaX to a partner.
Invoice
Sales Unit A sales unit that is set up at a sales partner and triggers orders.
Maintenance
A maintenance order to a technician for one or more sales units.
Job
This documentation is primarily intended to show what an Architecture Decision Report can
look like. This does not mean that such a simple description is sufficient for such a serious and
long-term decision as in the present case. Especially in this case, a deep analysis is of course
worthwhile, and the analysis results should then also be filed at this point!
Context
The basic technology of a software determines not only which APIs are available
for development, but also which ecosystem will have an influence on the
software in the long term. This ecosystem includes both free and proprietary
libraries and frameworks. The selected technology also determines future
viability, licensing costs and maintenance efforts.
In the course of setting up a new customer portal, a decision must be made about
which basic technology should be used.
State
Accepted.
Decision
Date of adoption of the resolution: 15.06.2015
A decision was made in favor of .NET and the Microsoft ecosystem as the basis
for software development at FotoMaX. .NET has been actively maintained by
Microsoft for many years, and it allows the development of rich clients as
needed for the sales units, websites, and mobile applications.
Consequences
Higher licensing costs are generally to be expected when using .NET and
Microsoft technologies as opposed to other technologies. These include the costs
for development environments, database servers and operating systems.
However, economies of scale can be exploited here by standardizing corporate
IT.
Context
The architecture review of May 12, 2019, determined that the architecture of the
Wizard is too difficult to maintain. Therefore, an alternative architecture is to be
developed. The following architecture samples have been compared to the
quality requirements to enable a selection. Please note: The evaluation was made
based an existing and complex software structure, which excludes a completely
new development.
Analyzability
Monolith Modulith SOA Microservices
Poor Good Medium Medium
Appropriateness
Authenticity
Completeness
Confidentiality
Fault Tolerance
Installability
Moduliths work as “deployment monoliths” and thus have the same advantage.
The infrastructure for installing microservices is more difficult to set up than the
infrastructure for just a few services.
Integrity
Interoperability
Services use open interfaces that facilitate connecting external services. The
Modulith is better prepared for such connections because it can be equipped with
the appropriate adapters more quickly than is the case with the Monolith.
Maturity
When used correctly, all architectural patterns can ensure the proper functioning
of the software system.
Modifiability
Monoliths are difficult to modify because their internal structure is less likely to
be decoupled and therefore changes to one part can affect other parts.
Microservices, on the other hand, operate as independently as possible.
Modularity
Microservices are the most modular systems possible. SOA depends on the
amount of and size of services. Moduliths are built with modularity in mind.
Recoverability
Monoliths only work as a whole, so errors are more likely to affect the entire
system. Moduliths have a greater chance of looking at individual components
separately than monoliths do. Service-oriented architectures are associated with
a whole range of tools that can be used to restore the status of individual services
as quickly as possible.
Testability
Moduliths are great to test because they can run as a whole but also divided in
their modules. Services based architectures are sometimes hard to test as a whole
and monoliths cannot be decomposed.
Time behavior
Decision
Accepted - 20.05.2019
The future Wizard will be implemented as a Modulith. This allows the best
backwards compatibility and a smooth migration of the existing system. The
actual advantages of service-oriented architectures and microservices cannot be
exploited in the case of the deployment scenario.
Consequences
This chapter is meant to show a more complex ADR as an example on how these can be used
to justify design decissions and strategies.
Context
Part of the further development of the Wizard is its decomposition into workflow
modules and service modules. This document describes which grouping and
priority should be taken into account in the decomposition. This is being
coordinated with various stakeholders. It should also be noted that this
decomposition is currently still very rough and is primarily intended as a
preparation for creating a minimally modular application. In a further
restructuring step, a functional decomposition can be performed on the basis of
the target architecture.
This contains
all driver
information and The hardware Since dialogs are
dialogs that connection area is primarily seen by
technicians manageable. technicians, the risk is
Hardware come into However, the dialogs comparatively low.
connection contact with are very rigid and not However, it can happen
during prepared for use in that technicians are
commissioning environments like the hindered in their work
and/or frame application. in case of errors.
maintenance of
sales units.
This group
The biggest risks come
describes all the
from the fact that the
logic that is
workflow engine has to
used for the
The code has to be be freely configurable
general
rewritten as much as and must not have any
implementation
possible because such dependencies to the
Workflow of dynamic
a procedure was not concrete workflows at
Engine workflows and
foreseen when the individual partners.
navigation. It is
existing application Since it is a central
not (!) about
was designed. control element, errors
the actual
here may have an
workflows, but
impact all the way to
only about their
the end customer.
infrastructure.
Due to the large
number of partners
Due to the large amount
and their respective
of code, the many
customizations, the
possible combinations,
Logos, Themes, effort required to
and the pervasiveness
Workflow extract the code is
of the application (some
Partner configurations very difficult to
assets are hardcoded),
Assets etc. for estimate. For some
the risk of overlooking
different partners, special
things that then become
partners adaptations were
apparent as errors
made to the Sales
directly to the customer
Unit, which must also
or partner is very high.
be reflected in a
restructured version.
Dialogs,
The same applies here
workflows, Here, the same applies
as with the partner
product as for the Partner
assets, only in an
descriptions, Assets, only in
Special increased form. Here,
etc., the use of increased form. The
Workflows the same applies as
which can be same applies here as for
for the Partner Assets,
configured via partner assets, only in
only in increased
the partner increased form.
form.
assets.
Decision
Accepted 27.11.2019
Due to the low effort and low risk of the conversion measures, it was decided to
first outsource the codecs and the image algorithms to a separate service module.
Although this does not serve the goal of a functional modularization of the
wizard, it does allow the migration to be run through once with a low investment
before more complex and riskier conversion measures are undertaken.
After the migration of the codecs and the image algorithms, the implementation
of the general workflow logic as an independent module will be pushed forward.
Again, this does not serve the long-term goal of functional modularization, but it
does allow such a central and important component to be decoupled and easily
testable from the outset.
Based on the resulting structures, the areas of partner assets and specific
workflows can then be implemented.
Consequences
While the initial modules will most likely not yet conform to the long-term
architecture, they will be designed to be easily adaptable. Once the workflow
logic has been implemented, further analysis of the legacy code and more
detailed planning of the migration will need to take place in consultation with
the various stakeholders.
This chapter shows how decission matrizes can be used to formalize the comparasion of
different solution alternatives.
Context
PRISM
Catel
WPF
Score 78 55
Description Rank
partial (Stack
overflow);
many base
How much
classes;
information
property bag
is available? excellently
Documentation 3 3 2 (Undo/Redo
How well is documented
available); One
it written? Is
man show but
it up-to-date?
fast reaction;
huge
community
How many
people are
4.2k stars, 1.2k 574 stars, 129
GitHub fame interested in 1 2 1
forks forks
the
framework?
wire
Is it possible
view/viewModel
to switch no special info
View Handling 3 3 declaratively in 1
between found
XAML (DI is
views?
possible)
EventAggregator;
messaging UI
Does it have via static
possible from
Messaging a message 2 3 background 3 Message
bus? threads is Mediator
possible
Does it
control how
the no, manual
Bootstrapping application is 2 3 integral part 0 registration at
started? Is IoC Container
the startup
structured?
Is it possible it seems so
to create (lack of
Module yes, lots of
modules and 2 3 1 documentation),
Handling different ways
load them it is not as good
dynamically? as Prism
Is it possible
to create and
UI Styling 1 0 not part of Prism 0 not part of Catel
manage
themes?
.NET
.NET 5
3 3 yes 2 Core
compatibility
3.1
Are there
helpers to
validate user
not part of Prism
Data input? Are
2 1 but WPF makes it 3 yes
Validation there helpers
possible
to show
validation
errors?
Are there
Costs licence fees? huge learning
moderate because
(including How long 2 2 excellent docu 2 cost because of
learning costs) might it take lack in docu
to learn?
How often is
it used? How
many
questions
can be found
950 downloads
Relevance on Stack 2 2 0 not measurable
per day
Overflow?
How easy is
it to find
information
about?
How long
does it exist?
Are there
Sustainability signs that it 3 3 yes 3 yes (2008)
will be
closed down
in the future?
Does it use
IoC? Does
Mockable for central no (everything
3 3 yes 0
testing services have is static)
abstract
interfaces?
It must be an
License approved 3 3 MIT 3 MIT
licence.
Decision
Accepted - 13.10.2020
The Prism framework was chosen as the application framework for the Wizard
because it meets all the requirements. Static code analysis must be used to ensure
that there are no dependencies on the framework outside of bootstrapping,
module definition and the user interface. In these parts, dependencies can be
tolerated, since there is a dependency on WPF here anyway. However, if a
platform-independent technology is chosen in the future, then a new
development of the entire wizard should not be necessary because of Prism!
Consequences
June 2021 an
attempt was
made to port the
wizard to .NET
5. This failed due
to various
reasons (see also A new migration
As time goes on,
Lessons attempt has been
the Wizard will
Porting the Learned). For planned for 2022.
use obsolete
wizard to this reason, the First the test coverage
R2 technology that is
.NET 5 was wizard was shall be increased,
no longer
not possible initially only and unsupported
supported by
upgraded to components shall be
Microsoft.
.NET 4.8, which replaced.
will not be
compatible with
newer .NET
versions in the
long run.
WPF mandates
WPF is used as the use of
the front-end Windows. The
technology of the licensing costs The incompatible
Wizard. The for Windows are libraries are replaced.
entire high compared to Then the application
WPF does
architecture of Linux is migrated to a
not allow
R3 the Wizard is distributions. The newer .NET version.
platform
geared towards WPF add-on Then the need for
independence
the use of WPF libraries used in platform
and thus the software independence is re-
replacement is hinder the actual evaluated.
not easily compatibility to
possible. newer .NET
versions.
Term Description
Image files, color definitions, fonts, workflows, etc., through which
Assets the Sales Unit is adapted to the corporate identity of a pitch
provider.
Pitch A company that offers photo printing services via FotoMaX and
provider provides a space for this purpose on their own premises.
Print
Companies that carry out print jobs.
provider
This chapter contains information that does not relate directly to the software
architecture, but to the day-to-day collaboration in implementing the software.
Onboarding
Note that this chapter is a direct result of the quality requirements and scenarios regarding
maintainability which states that new team members should be able to be productive in a
certain amount of time.
This chapter describes resources to help new team members get the best possible
start on the project.
The following checklist is intended to help new team members find their way
around the team as quickly as possible and be able to work productively.
Contact
Check Work Item Reference Material
Person
Scrum Scrum Guide, Agile
▢ Basics of agile working
Master Manifesto
Clarification of how the
Scrum Team Charter, Definition of
▢ team has adapted the agile
Master Ready, Definition of Done
work
Invitation to regular Scrum Daily, Review, Planning,
▢
meetings Master Retro, Refinement
Scrum
▢ Invitation to agile tools Teamretro, Miro
Master
Introduction to used agile Scrum scrum-poker.org, Teamretro,
▢
tools Master Miro
Product Marketing Documentation,
▢ Introduction to product
Owner User Manual, Test System
Introduction to architecture
▢ Architect Architecture Documentation
documentation
Read and understand New
▢ Architecture Documentation
architecture documentation Member
Set up development New
▢ Installation Guide
environment Member
Overview of the Coding Guidelines, Review
▢ Developer
development process Guidelines
Testing Guidelines, Testing
Overview of test
▢ Developer Frameworks, Test isolation
procedures and tools used
Frameworks
New
▢ Read past sprint reviews Sprint Reviews
Member
New
▢ Implement Tutorial Tutorial
Member
New
▢ Checkout Repository Git Repository
Member
Write first test in New
▢ Source Code
production code Member
Installation Guide
In a real documentation, this chapter would describe of how to set up a new development
environment. Among other things, the following questions should be answered: * Which
software is to be installed in which order? * Which environment variables or similar have to be
set? * From where can the source code be obtained?
Tutorial
In a real documentation, a description would be found in this chapter, with which new team
members can develop a first feature. This helps them to understand the basic architecture and
the tools used, but also to test their development environment before they write their first real
production code.
Guidelines
Coding Guidelines
This chapter would contain descriptions of how the code should be styled, if this was a real
documentation. In general, the coding guidelines should mainly deal with special cases instead
of explaining the code style in detail. The latter can be better checked by static code analysis
tools and/or a linters. Things to consider are for example: * Mention of the code style used
with a link to additional sources and incl. explanation of how it is checked. * Dealing with
exceptions (if supported by the language) * Dealing with enumerations (if supported by the
language) * Common (Anti-)Patterns to avoid
Testing Guidelines
This chapter should contain descriptions on how automated or manual tests are to be
performed. It is worthwhile at this point to formulate guidelines individually for each type of
test in order to be able to design them in a way that is appropriate for the target group. * Unit
Test Guidelines * Integration Test Guidelines * Exploratory Test Guidelines * …
Review Guidelines
Code reviews are a very important means of quality assurance. This document is
intended to provide reviewers with a guideline to decide whether or not a pull
request may be included in the main branch. This guideline only includes things
that are not already checked by an automated check through build tools.
Precondition of a review
Check Description
The review is performed by a person who was not involved in the
▢
programming himself.
▢ The code was checked out locally by the reviewer.
▢ The code was built locally.
▢ Automated tests were executed locally.
Criteria
Check Description
▢ The software was built successfully.
The software can be started locally and simple operations in the area
▢
of the change are possible without complications.
No exceptions were detected during the execution of the code (see
▢
Exception Information of the debugger).
▢ All automated tests can be executed successfully.
▢ There are no ignored tests.
If tests were deleted, this was done justifiably or they were replaced
▢
by others.
▢ There are no warnings in the local development environment.
▢ There is no code that suppresses warnings in the code analysis tools.
▢ The code satisfies the rules from the Coding Guidelines.
▢ The tests satisfy the rules from the Testing Guidelines.
Daily Work
This part of the documentation is reserved for all topics regarding the
organization of the daily work of the team.
This area would be separately handled for each and every team. Following only one example
can be found to hold the overall documentation short.
Team Charter
The team charter is a set of rules created by each team itself to define how it
wants to work together. It should only contain things that all members can agree
on. Examples:
We are punctual.
Problems are resolved promptly and factually.
Documentation and testing are as important as source code.
We maintain a positive feedback culture.
Cell phones may not be used during an appointment.
Definition of Ready
With the Definition of Ready, the team determines which prerequisites must be
met before the actual development can start. The DoR was created by the team
and each team member agreed on it.
The requirements are described as user stories and placed in the backlog.
The user story has been assigned a business value.
The user story is understood by all team members.
Testable acceptance criteria are available.
External dependencies have been named.
The user story has been estimated in story points.
Definition of Done
With the Definition of Done, the team determines when it is finally finished with
the work on a feature. The DoD was created by the team and each team member
agreed on it.
A code review was performed by a developer who was not involved in the
implementation.
All acceptance criteria have been implemented.
Test coverage is at least 75%.
All tests are successful.
The code has been transferred to the Main Branch.
There was a formal review by the product owner.
Sprint Reviews
Results or resources from and for the sprint reviews can be stored in this area. In this way, the
information is not lost and can contribute to continuous improvement.
Vacation Planning
If there is no better solution, this area of the documentation can be used to track
the availability of team members and plan vacations. This allows a more
effective sprint planning.
VIII - Mac-OS Menubar Application
By Gernot Starke.
This surely is one of the shortest and most compact architecture documentations.
Its goal is to show that arc42 can be extremely tailored and reduced to keep only
a minimal amount of documentation.
Since then he has consulted and coached numerous clients from various
domains, mainly finance, insurance, telecommunication, logistics, automotive
and industry on topics around software engineering, software development and
development process organization.
Gernot was an early adopter of the agile movement and has successfully worked
as Scrum master in agile projects.
He lives in Cologne with his wife (Cheffe Uli) and his two (nearly grown-up)
kids, two cats and a few Macs.
About embarc
Gernot Starke
Just email Gernot Starke or contact him via Twitter as @gernotstarke.
Hendrik Lösch
Just email Hendrik Lösch or contact him via his website hendrik-loesch.de.
Michael Simons
Just email Michael Simons or contact him via Twitter as @rotnroll666.
Ralf D. Müller
Just email Ralf D. Müller or contact him via Twitter: @RalfDMueller.
Stefan Zörner
Just email Stefan Zörner or contact him via Twitter: @StefanZoerner.
Further Reading
If you liked the way we explained, communicated and documented software
architectures, you might want to know more about arc42.
This practical guide shows how you can effectively apply the practical and well-
proven arc42 template to design, develop and document your software
architecture.
It contains more than 200 practical tips how to improve your architecture
communication and documentation:
More than 150 questions around arc42 topics - available for free as eBook and
online.
In addition to definitions this eBook also contains translation tables, currently for
German and English.
The German original of the previously mentioned eBook… for those who both
understand German and like to hold books in their hands…
3 The real company behind the MaMa-CRM system prefers not to be disclosed
here. The name InDAC (= Innovative data center) is therefore pure fantasy. The
original system wasn’t called MaMa, but had a different name – I hope you don’t
mind.↩
4 In some countries or for some contract types there might be simpler solutions
than a written signature. Please ignore that for the moment.↩
6 In the real system, billing and payment was usually processed by the
mandators (!) - but these 3-party processes are not significant for the software
architecture, and therefore left out of this documentation.↩