I - Introduction

This book contains several examples of Software Architecture Documentation based upon the practical, economical, well-established and systematic arc42 approach.

It shows how you can communicate about software architectures, but it does not show how to develop or implement systems!

I.1 What is arc42?

arc42 is a template for architecture documentation.

It answers the following two questions in a pragmatic way, but can be tailored to your specific needs:

• What should we document/communicate about our architecture?
• How should we document/communicate?

Figure I.1 gives you the big picture: It shows a (slightly simplified) overview of the structure of arc42.

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

arc42 is optimized for understandability and adequacy. It naturally guides you to explain any kind of architecture information or decision in an understandable and reproducible context.

Individuals and organizations using arc42 especially like two things about it:

1. the understandability of the documentation resulting from its standardized structure (the drawers) and
2. the manageable effort to create such documentation. We call it “painless documentation”.

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:

arc42 aims at providing the answer to everything around your software architecture. (Yes, I know it’s a little pretentious, but we couldn’t think of a better name back in 2005.)

Where to get additional information

With the latest release (V7) of arc42 in January 2017, the project now has extensive online help and FAQ (frequently asked questions) available:

• The documentation site docs.arc42.org contains the full documentation plus many (more than 100) tips for efficient and effective usage.
• The FAQ site faq.arc42.org answers more than 100 typical questions.

I.2 Why this Book?

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.

After an incredibly successful (again, German only) experiment to publish one single example as a (very skinny) 40-page booklet we decided to publish a collection of examples on a modern publishing platform - so we can quickly react to user feedback and add further samples without any hassle.

I.3 What this Book is Not

In this book we focus on examples for arc42 to document and communicate software architectures. We only give a brief introduction to arc42 (in case you like more, see appendix B for details)

This book is no introduction to:

• 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

We encountered exciting software and system architectures during our professional lifes. Several of those would have made instructive, interesting and highly relevant examples - too bad they were declared confidential by their respective owners. Our nondisclosure agreements stated that we’re not allowed to even mention clients’ names without violating these contracts…

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…

HTML Sanity Checking

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.

HtmlSanityCheck (or HtmlSC for short) is described in chapter II of this book.

Mass Market Customer Relationship Management

Gosh, what an awkward name - so let’s shorten it to MaMa-CRM at first: Mass market refers to consumers of severl kinds of enterprises, like health insurance, mobile telecommunication or large real-estate companies.

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…

MaMa-CRM takes the burden of (usually paper-based) customer contacts from the organizations working in such mass markets. It has been initially build by an independent mid-sized data center to support the launch of the German (government-enforced) e-Health-Card - and later on used to support campaigns like telephone billing, electrical-power metering and similar stuff.

The architecture of MaMa-CRM is covered in chapter III.

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.

The architecture of biking2 is covered in chapter IV

DokChess - a Chess Engine

DokChess is a fully functional chess engine.

The architecture of DokChess is covered in chapter V

docToolchain

docToolchain is a heavily used and highly practical implementation of the docs-as-code approach: The basic idea is to facilitate creation and maintenance of technical documentation.

The architecture of docToolchain is covered in chapter VI

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.

Foto Max can be found in chapter VII

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.

Skip to chapter VIII to see for yourself.