About arc42

arc42, the template for documentation of software and system architecture.

Template Version 0.1 EN. Stefan Kapferer, July 2023

Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors. See https://arc42.org.


This documentation and the implementation of the sample app is always work in progress and by no means complete. We continuously evolve it and use the repo for illustrating different approaches around DDD and Context Mapper.

1. Introduction and Goals

This DDD and Context Mapper Sample Application aims to illustrate how to:

  • Verify domain implementation against a Context Mapper model (tactic DDD) using the Context Mapper ArcUnit extension.

    • We use jMolecules annotations to assign DDD patterns to the Java classes.

  • Use Context Mapper generator outputs (for example PlantUML diagrams) in your architecture documentation.

  • Implement an application using the tactic DDD patterns and Onion Architecture (just one example; others might do it differently).

In order to provide such a sample application we needed a domain. We decided for something that is very simple, as this serves our goals (giving an example for the above points and use the application in teaching/workshops) best.

Note: We are aware that the sample domain (three letter abbreviations) would most likely too simple in a real world scenario to justify the application of DDD. For such a simple thing, you would probably not need DDD.

The idea of the sample: An application that can resolve and manage three letter abbreviations and their meanings. Users can for example integrate it in their tool-chain to automatically generate list of abbreviations in their documents.

1.1. Requirements Overview

The main idea of the application is to offer a TLA (three letter abbreviation)[1] resolver via a RESTful HTTP API. Users can resolve TLAs meanings by using the API. Additionally, users shall be able to post new TLAs. Those are then reviewed and made public by power users.

The following use case diagram illustrates the main features:


1.2. Quality Goals


1.3. Stakeholders

Role/Name Contact Expectations

Context Mapper Project Team


Have an example for teaching purposes.

Context Mapper Users

Find an example that shows how Context Mapper can be integrated into a project.

to be continued …​

2. Architecture Constraints

3. System Scope and Context

3.1. Business Context

<Diagram or Table>

<optionally: Explanation of external domain interfaces>

3.2. Technical Context

<Diagram or Table>

<optionally: Explanation of technical interfaces>

<Mapping Input/Output to Channels>

4. Solution Strategy

5. Building Block View

5.1. Whitebox Overall System

<Overview Diagram>


<text explanation>

Contained Building Blocks

<Description of contained building block (black boxes)>

Important Interfaces

<Description of important interfaces>

5.1.1. <Name black box 1>



<(Optional) Quality/Performance Characteristics>

<(Optional) Directory/File Location>

<(Optional) Fulfilled Requirements>

<(optional) Open Issues/Problems/Risks>

5.1.2. <Name black box 2>

<black box template>

5.1.3. <Name black box n>

<black box template>

5.1.4. <Name interface 1>


5.1.5. <Name interface m>

5.2. Level 2

5.2.1. White Box <building block 1>

<white box template>

5.2.2. White Box <building block 2>

<white box template>


5.2.3. White Box <building block m>

<white box template>

5.3. Level 3

5.3.1. White Box <_building block x.1_>

<white box template>

5.3.2. White Box <_building block x.2_>

<white box template>

5.3.3. White Box <_building block y.1_>

<white box template>

6. Runtime View

6.1. <Runtime Scenario 1>

  • <insert runtime diagram or textual description of the scenario>

  • <insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>

6.2. <Runtime Scenario 2>

6.3. …​

6.4. <Runtime Scenario n>

7. Deployment View

7.1. Infrastructure Level 1

<Overview Diagram>


<explanation in text form>

Quality and/or Performance Features

<explanation in text form>

Mapping of Building Blocks to Infrastructure

<description of the mapping>

7.2. Infrastructure Level 2

7.2.1. <Infrastructure Element 1>

<diagram + explanation>

7.2.2. <Infrastructure Element 2>

<diagram + explanation>


7.2.3. <Infrastructure Element n>

<diagram + explanation>

8. Concepts

8.1. Domain Model


8.2. TLA States


9. Architecture Decisions

10. Quality Requirements

10.1. Quality Tree

10.2. Quality Scenarios

11. Risks and Technical Debts

12. Glossary

Term Definition





1. TLA: 'Three Letter Abbreviation' or also 'Three Letter Acronym'