About arc42

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

Template Version {revnumber}. {revremark}, {revdate}

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

1. Introduction and Goals

Describes the relevant requirements and the driving forces that software architects and development team must consider. These include

  • underlying business goals, essential features and functional requirements for the system

  • quality goals for the architecture

  • relevant stakeholders and their expectations

1.1. Requirements Overview

Contents

Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).

Motivation

From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.

Form

Short textual description, probably in tabular use-case format. If requirements documents exist this overview should refer to these documents.

Keep these excerpts as short as possible. Balance readability of this document with potential redundancy w.r.t to requirements documents.

  • Generate Hamcrest matchers for model/domain classes at compile time

  • No production-code pollution - configuration uses a SOURCE-retention annotation only, leaving model classes untouched

  • Compile-safe alternative to Hamcrest’s hasProperty() / HasPropertyWithValue

  • Informative mismatch messages via the generated fluent API

  • Lombok-annotated classes are supported

  • Works with plain Java and Kotlin (via KAPT)

1.2. Quality Goals

Contents

The top three (max five) quality goals for the architecture whose fulfillment is of highest importance to the major stakeholders. We really mean quality goals for the architecture. Don’t confuse them with project goals. They are not necessarily identical.

Motivation

You should know the quality goals of your most important stakeholders, since they will influence fundamental architectural decisions. Make sure to be very concrete about these qualities, avoid buzzwords. If you as an architect do not know how the quality of your work will be judged …

Form

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

Priority Quality Motivation

1

Correctness

Generated matchers must be type-safe and compile without errors - broken generation is worse than no generation

2

Non-intrusiveness

The core design promise: zero footprint on production code; SOURCE retention means no runtime dependency bleeds into model classes

3

Usability

The generated fluent API must be discoverable and ergonomic for test writers

4

Build-tool agnosticism

Works via standard APT (javac) and KAPT (kotlinc); no coupling to a specific build plugin

5

Maintainability

The generator codebase must remain understandable and extensible for contributors

1.3. Stakeholders

Contents

Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that

  • should know the architecture

  • have to be convinced of the architecture

  • have to work with the architecture or with code

  • need the documentation of the architecture for their work

  • have to come up with decisions about the system or its development

Motivation

You should know all parties involved in development of the system or affected by the system. Otherwise, you may get nasty surprises later in the development process. These stakeholders determine the extent and the level of detail of your work and its results.

Form

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

Role/Name Contact Expectations

Test engineers / Java-Kotlin developers

GitHub Issues

Stable, backwards-compatible releases; correct and ergonomic generated matchers; reliable Maven Central artifacts

Contributors (incl. maintainer marmer)

https://github.com/marmer/hamcrest-matcher-generator

Understandable architecture; clear contribution path; well-tested generator code

2. Architecture Constraints

3. Context and Scope

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>

Motivation

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

<Purpose/Responsibility>

<Interface(s)>

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

Motivation

<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. Cross-cutting Concepts

8.1. <Concept 1>

<explanation>

8.2. <Concept 2>

<explanation>

…​

8.3. <Concept n>

<explanation>

9. Architecture Decisions

10. Quality Requirements

10.1. Quality Requirements Overview

10.2. Quality Scenarios

11. Risks and Technical Debts

12. Glossary

Term Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>