Merge branch 'issue-7'

.gitignore

@@ -0,0 +1,2 @@
+target
+**/.DS_Store

pom.xml

@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>ch.bfh.ipst.dsl</groupId>
+  <artifactId>civil42</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+
+  <name>civil42</name>
+  <url>https://github.com/digital-sustainability/civil42</url>
+
+  <properties>
+        <asciidoctor-maven-plugin.version>3.0.0</asciidoctor-maven-plugin.version>
+        <asciidoctorj.version>2.5.12</asciidoctorj.version>
+        <asciidoctorj-pdf.version>2.3.15</asciidoctorj-pdf.version>
+        <asciidoctorj-pdf.plugin.version>2.3.15</asciidoctorj-pdf.plugin.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
+  <dependencies>
+      <dependency>
+          <groupId>org.asciidoctor</groupId>
+          <artifactId>asciidoctorj</artifactId>
+          <version>${asciidoctorj.version}</version>
+      </dependency>
+      <dependency>
+          <groupId>org.asciidoctor</groupId>
+          <artifactId>asciidoctorj-pdf</artifactId>
+          <version>${asciidoctorj-pdf.version}</version>
+      </dependency>
+  </dependencies>
+
+  <build>
+        <plugins>
+            <plugin>
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+                <version>${asciidoctor-maven-plugin.version}</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.asciidoctor</groupId>
+                        <artifactId>asciidoctorj-pdf</artifactId>
+                        <version>${asciidoctorj-pdf.plugin.version}</version>
+                    </dependency>
+                </dependencies>
+                <executions>
+                    <execution> 
+                        <id>output-html</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <backend>html</backend>
+                            <attributes>
+                                <toc/>
+                                <linkcss>false</linkcss>
+                                <source-highlighter>coderay</source-highlighter>
+                                <imagesdir>images</imagesdir>
+                            </attributes>
+                            <outputDirectory>target/docs/html</outputDirectory>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>output-pdf</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                    </execution>
+                    <execution>
+                        <id>asciidoc-to-docbook</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <backend>docbook</backend>
+                            <doctype>book</doctype>
+                            <attributes>
+                                <imagesdir>images</imagesdir>
+                            </attributes>
+                            <outputDirectory>target/docs/docbook</outputDirectory>
+                        </configuration>
+                    </execution>
+                </executions>
+                <configuration>
+                    <backend>pdf</backend>
+                    <doctype>book</doctype>
+                    <outputDirectory>target/docs/pdf</outputDirectory>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>3.1.0</version>
+                <executions>
+                    <execution>
+                        <phase>verify</phase>
+                        <goals>
+                            <goal>exec</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                <executable>pandoc</executable>
+                <!-- optional -->
+                <workingDirectory>target</workingDirectory>
+                <arguments>
+                    <argument>-f</argument>
+                    <argument>docbook</argument>
+                    <argument>-s</argument>
+                    <argument>docs/docbook/arc42.xml</argument>
+                    <argument>-o</argument>
+                    <argument>docs/arc42.docx</argument>
+                </arguments>
+                <environmentVariables>
+                    <LANG>de_DE</LANG>
+                </environmentVariables>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

src/docs/asciidoc/arc42.adoc

@@ -0,0 +1,98 @@
+// header file for arc42-template,
+// including all help texts
+//
+// ====================================
+
+
+// configure DE settings for asciidoc
+include::content/config.adoc[]
+
+= image:arc42-logo.png[arc42] Template
+:revnumber: 8.2 DE
+:revdate: Januar 2023
+:revremark: (basiert auf AsciiDoc Version)
+// toc-title definition MUST follow document title without blank line!
+:toc-title: Inhaltsverzeichnis
+
+//additional style for arc42 help callouts
+ifdef::backend-html5[]
+++++
+<style>
+.arc42help {font-size:small; width: 14px; height: 16px; overflow: hidden; position: absolute; right: 0; padding: 2px 0 3px 2px;}
+.arc42help::before {content: "?";}
+.arc42help:hover {width:auto; height: auto; z-index: 100; padding: 10px;}
+.arc42help:hover::before {content: "";}
+@media print {
+	.arc42help {display:none;}
+}
+</style>
+++++
+endif::backend-html5[]
+
+
+include::content/about-arc42.adoc[]
+
+// horizontal line
+***
+
+[role="arc42help"]
+****
+[NOTE]
+====
+Diese Version des Templates enthält Hilfen und Erläuterungen.
+Sie dient der Einarbeitung in arc42 sowie dem Verständnis der Konzepte.
+Für die Dokumentation eigener System verwenden Sie besser die _plain_ Version.
+====
+****
+
+
+// numbering from here on
+:numbered:
+
+<<<<
+// 1. Anforderungen und Ziele
+include::content/01_introduction_and_goals.adoc[]
+
+<<<<
+// 2. Randbedingungen
+include::content/02_architecture_constraints.adoc[]
+
+<<<<
+// 3. Kontextabgrenzung
+include::content/03_system_scope_and_context.adoc[]
+
+<<<<
+// 4. Lösungsstrategie
+include::content/04_solution_strategy.adoc[]
+
+<<<<
+// 5. Bausteinsicht
+include::content/05_building_block_view.adoc[]
+
+<<<<
+// 6. Laufzeitsicht
+include::content/06_runtime_view.adoc[]
+
+<<<<
+// 7. Verteilungssicht
+include::content/07_deployment_view.adoc[]
+
+<<<<
+// 8. Querschnittliche Konzepte
+include::content/08_concepts.adoc[]
+
+<<<<
+// 9. Entscheidungen
+include::content/09_architecture_decisions.adoc[]
+
+<<<<
+// 10. Qualitätsanforderungen
+include::content/10_quality_requirements.adoc[]
+
+<<<<
+// 11. Risiken
+include::content/11_technical_risks.adoc[]
+
+<<<<
+// 12. Glossar
+include::content/12_glossary.adoc[]

src/docs/asciidoc/content/01_introduction_and_goals.adoc

@@ -0,0 +1,89 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-introduction-and-goals]]
+==	Einführung und Ziele
+
+[role="arc42help"]
+****
+Beschreibt die wesentlichen Anforderungen und treibenden Kräfte, die bei der Umsetzung der Softwarearchitektur und Entwicklung des Systems berücksichtigt werden müssen.
+
+Dazu gehören:
+
+* zugrunde liegende Geschäftsziele,
+* wesentliche Aufgabenstellungen,
+* wesentliche funktionale Anforderungen,
+* Qualitätsziele für die Architektur und
+* relevante Stakeholder und deren Erwartungshaltung.
+****
+
+=== Aufgabenstellung
+
+[role="arc42help"]
+****
+.Inhalt
+Kurzbeschreibung der fachlichen Aufgabenstellung, treibenden Kräfte, Extrakt (oder Abstract) der Anforderungen.
+Verweis auf (hoffentlich vorliegende) Anforderungsdokumente (mit Versionsbezeichnungen und Ablageorten).
+
+.Motivation
+Aus Sicht der späteren Nutzung ist die Unterstützung einer fachlichen Aufgabe oder Verbesserung der Qualität der eigentliche Beweggrund, ein neues System zu schaffen oder ein bestehendes zu modifizieren.
+
+.Form
+Kurze textuelle Beschreibung, eventuell in tabellarischer Use-Case Form.
+Sofern vorhanden, sollte die Aufgabenstellung Verweise auf die entsprechenden Anforderungsdokumente enthalten.
+
+Halten Sie diese Auszüge so knapp wie möglich und wägen Sie Lesbarkeit und Redundanzfreiheit gegeneinander ab.
+
+
+.Weiterführende Informationen
+
+Siehe https://docs.arc42.org/section-1/[Anforderungen und Ziele] in der online-Dokumentation (auf Englisch!).
+
+****
+
+=== Qualitätsziele
+
+[role="arc42help"]
+****
+.Inhalt
+Die Top-3 bis Top-5 der Qualitätsanforderungen für die Architektur, deren Erfüllung oder Einhaltung den maßgeblichen Stakeholdern besonders wichtig sind.
+Gemeint sind hier wirklich Qualitätsziele, die nicht unbedingt mit den Zielen des Projekts übereinstimmen. 
+Beachten Sie den Unterschied.
+
+Hier ein Überblick möglicher Themen (basierend auf dem ISO 25010 Standard):
+
+image::01_2_iso-25010-topics-DE.drawio.png["Kategorien von Qualitätsanforderungen"]
+
+.Motivation
+Weil Qualitätsziele grundlegende Architekturentscheidungen oft maßgeblich beeinflussen, sollten Sie die für Ihre Stakeholder relevanten Qualitätsziele kennen, möglichst konkret und operationalisierbar.
+
+.Form
+Tabellarische Darstellung der Qualitätsziele mit möglichst konkreten Szenarien, geordnet nach Prioritäten.
+****
+
+=== Stakeholder
+
+[role="arc42help"]
+****
+.Inhalt
+Expliziter Überblick über die Stakeholder des Systems – über alle Personen, Rollen oder Organisationen –, die
+
+* die Architektur kennen sollten oder
+* von der Architektur überzeugt werden müssen,
+* mit der Architektur oder dem Code arbeiten (z.B. Schnittstellen nutzen),
+* die Dokumentation der Architektur für ihre eigene Arbeit benötigen,
+* Entscheidungen über das System und dessen Entwicklung treffen.
+
+.Motivation
+Sie sollten die Projektbeteiligten und -betroffenen kennen, sonst erleben Sie später im Entwicklungsprozess Überraschungen.
+Diese Stakeholder bestimmen unter anderem Umfang und Detaillierungsgrad der von Ihnen zu leistenden Arbeit und Ergebnisse.
+
+.Form
+Tabelle mit Rollen- oder Personennamen, sowie deren Erwartungshaltung bezüglich der Architektur und deren Dokumentation.
+****
+
+[cols="1,1,2" options="header"]
+|===
+|Rolle |Kontakt |Erwartungshaltung
+| _<Rolle-1>_ | _<Kontakt-1>_ | _<Erwartung-1>_
+| _<Rolle-2>_ | _<Kontakt-2>_ | _<Erwartung-2>_ 
+|===

src/docs/asciidoc/content/02_architecture_constraints.adoc

@@ -0,0 +1,25 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-architecture-constraints]]
+== Randbedingungen
+
+[role="arc42help"]
+****
+.Inhalt
+Randbedingungen und Vorgaben, die ihre Freiheiten bezüglich Entwurf, Implementierung oder Ihres Entwicklungsprozesses einschränken.
+Diese Randbedingungen gelten manchmal organisations- oder firmenweit über die Grenzen einzelner Systeme hinweg.
+
+.Motivation
+Für eine tragfähige Architektur sollten Sie genau wissen, wo Ihre Freiheitsgrade bezüglich der Entwurfsentscheidungen liegen und wo Sie Randbedingungen beachten müssen.
+Sie können Randbedingungen vielleicht noch verhandeln, zunächst sind sie aber da.
+
+.Form
+Einfache Tabellen der Randbedingungen mit Erläuterungen.
+Bei Bedarf unterscheiden Sie technische, organisatorische und politische Randbedingungen oder übergreifende Konventionen (beispielsweise Programmier- oder Versionierungsrichtlinien, Dokumentations- oder Namenskonvention).
+
+
+.Weiterführende Informationen
+
+Siehe https://docs.arc42.org/section-2/[Randbedingungen] in der online-Dokumentation (auf Englisch!).
+
+****