Architecture documentation of A Fictitious Application

About this project

This project is a demo project to demonstrate the architecture documentation with the help of the docToolchain.

The aim is to demonstrate how the docToolchain can be used to deploy architecture documentation according to arc42 and the doc-as-code approach (see Documentation As Code and Write The DOCS: Docs as Code) into different formats, even into Confluence.

The documents are written with Asciidoc. The diagrams with plantUML.

At the same time, this project serves as an example of how a system architecture can be documented. The contents of the individual chapters, according to arc42, are used for this purpose.

If you are interested in the sources of this documentation, check the repository on gitlab.

About arc42

arc42

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

Template Version 8.2 EN. (based upon AsciiDoc version), January 2023

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

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

The application is used in the context described here.

The aim is to show where the limits of the application are, both professionally and technically.

3.1. Business Context

{plantUMLDir}businessContext
Figure 1. Business Context
Table 1. Business Context of the components
Component Descritpion

User

Administrator

Analyst

Application

System

<optionally: Explanation of external domain interfaces>

3.2. Technical Context

{plantUMLDir}technicalContext
Figure 2. Technical Context
Table 2. Technical context of the components
Component Descritpion

User

Administrator

Analyst

Application

System

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

10.2. Quality Scenarios

11. Risks and Technical Debts

12. Glossary

Term Definition

<Term-1>

<definition-1>

<Term-2>

<definition-2>