About arc42

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

Template Version 8.1 EN. (based upon AsciiDoc version), May 2022

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

1. Introduction and Goals

Far in the past there was the phplib template engine which was simple and easy to use. During working with this engine over some years I have optimized it and ported it to the java programming language. During the time the template engine has been made more safe and secure by using static analysis tools. Usage of this template engine is for webpages as well as for code generators and everything else you could imagine.

1.1. Requirements Overview

Functional requirements are:

  • Has templates

  • Can read templates from files

  • Can replace variables within content

  • Can append content to variables

  • Can cut out blocks from templates/blocks and replace them with a variable

  • Can have blocks within blocks

It is a small and fast template engine that divides cleanly between the designer and the software engineer.

Further Information

1.2. Quality Goals

The top quality goals are:

  • Compatibility with phplib template engine

  • Performace efficience

  • Low memory usage

  • Security/Safety

  • Usability

  • Transferability

1.3. Stakeholders

The first stakeholder is the developer itself for his other projects. Second stakeholders are all other java or jvm language developers around the world, because it’s an open source project.

Role/Name Contact Expectations

Kai Hofmann

powerstat@web.de

Stable api, secure, fast, simple

Every developer

unknown

Stable api, secure, fast, simple

2. Architecture Constraints

Architecture constraints are as follows:

  • Open source

  • Compatible in api and template format with the original phplib template engine

  • Given configurations for CheckStyle, PMD, SpotBugs, SonarQube have to be used

  • For documentation uml, javadoc and asciidoc have to be used

3. System Scope and Context

The System context is related to every Java programm or other languages thet run on the jvm/graalvm. Communication could happen vis Strings, Files or Streams.

3.1. Business Context

The template engine is a library that could be used by other developers within the java / jvm context.

3.2. Technical Context

Technical interfaces in Java are:

  • String (in/out)

  • File (in)

  • InputStream (in)

4. Solution Strategy

Java has been choosen as programming language, because it is widely used.

The template engine has been ported 1:1 in a first step and then improved over time.

To archive key quality goals free available static analysis tools have been introduced and the ruleset (if possible) have been self made for high quality. Also unit tests have been applied with using mutation testing (pitest) and high code coverage (jacoco). Also Eclipse configurations to reach high quality have been made.

5. Building Block View

building block

5.1. Whitebox Overall System

whitebox diagram

6. Runtime View

6.1. <Runtime Scenario 1>

activity diagram1

6.2. <Runtime Scenario 2>

activity diagram2

6.3. <Runtime Scenario 3>

activity diagram3

6.4. <Runtime Scenario 4>

activity diagram4

7. Deployment View

7.1. Infrastructure Level 1

component diagram

8. Cross-cutting Concepts

8.1. Domain concepts

To be done

8.2. Safety and security concepts

See development concepts

8.3. Architecture and design patterns

To be done.

8.4. Development concepts

  • Java

  • Maven

  • CheckStyle with own rules

  • PMD with own rules

  • SpotBugs with plugins

  • SonarQube

  • Unit-Tests with pitest and jacoco

9. Architecture Decisions

  • PHPLib template engine - because of it' simplenest

  • Java - because its a better language than C++ and white spread

  • Block loop logic is still within the code and not in the template

  • Template syntax is XML compatible but could alos be used for code templates

10. Quality Requirements

10.1. Quality Tree

quality tree

10.2. Quality Scenarios

use case

11. Risks and Technical Debts

The following risks exists at the moment:

  • Unknown memory consumption

  • Unknown performance issues

  • Unknown security problems

12. Glossary

Term Definition

Block

Area that can be cut out from a template to replace it one or multiple times with new content

GraalVM

Graal virtual machine, successor of JVM

Java

The java programming language

JVM

Java virtual machine

Template

UTF-8 string with replaceable elements

TemplateEngine

A program that allows to replace variables and blocks within a template

Variable

A replaceable variable within a template