Software Architecture Documentation with arc42, C4 model and Documentation as Code

1. Introduction and Goals

1.1. Requirements Overview

1.2. Quality Goals

1.3. Stakeholders

Role/Name Contact Expectations

<Role-1>

<Contact-1>

<Expectation-1>

<Role-2>

<Contact-2>

<Expectation-2>

2. Architecture Constraints

3. System Scope and Context

3.1. Business Context

Diagram

Legende

Diagram

<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. Internet Banking System

Diagram

Legende

Diagram

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

Diagram

Legende

Diagram

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

Diagram

Legende

Diagram

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

7. Deployment View

7.1. Infrastructure Level 1

Diagram

Legend

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

9.1. Decision A

Date: 2023-02-21

9.1.1. Status

Accepted

9.1.2. Context

The issue motivating this decision, and any context that influences or constrains the decision.

9.1.3. Decision

The change that we’re proposing or have agreed to implement.

9.1.4. Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

9.2. Decision B

Date: 2023-02-21

9.2.1. Status

Accepted

9.2.2. Context

The issue motivating this decision, and any context that influences or constrains the decision.

9.2.3. Decision

The change that we’re proposing or have agreed to implement.

9.2.4. Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

9.3. Decision C

Date: 2023-02-21

9.3.1. Status

Accepted

9.3.2. Context

The issue motivating this decision, and any context that influences or constrains the decision.

9.3.3. Decision

The change that we’re proposing or have agreed to implement.

9.3.4. Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

10. Quality Requirements

10.1. Quality Tree

10.2. Quality Scenarios

11. Risks and Technical Debts

12. Glossary

Term Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>