doc: software architecture document

.github/workflows/build.yml

@@ -5,7 +5,7 @@ name: Build project
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "main", "feature/*", "issue/*", "doc/*" ]
   pull_request:
     branches: [ "main" ]
 

.gitignore

@@ -9,6 +9,9 @@ target/
 .idea/compiler.xml
 .idea/libraries/
 .idea/GitlabLint.xml
+.idea/misc.xml
+.idea/gradle.xml
+.idea/workspace.xml
 *.iws
 *.iml
 *.ipr
@@ -45,4 +48,3 @@ build/
 
 # ignore generated user manuals
 /src/main/resources/ch/admin/bar/siardsuite/doc/
-.idea

build.gradle

@@ -6,6 +6,7 @@ plugins {
     id 'org.asciidoctor.jvm.pdf' version '3.3.2'
     id 'pl.allegro.tech.build.axion-release' version '1.14.3'
     id 'io.freefair.lombok' version '6.5.0'
+    id 'com.cosminpolifronie.gradle.plantuml' version '1.6.0'
 }
 
 repositories {
@@ -219,11 +220,19 @@ asciidoctorPdf {
     dependsOn(asciidoctor)
 }
 
+plantUml {
+    render input: 'docs/sad/diagrams/*.puml', output: 'docs/sad/diagrams/generated', format: "png"
+}
+
 tasks.register('copyDocumentation', Copy) {
     from layout.buildDirectory.dir("docs/pdf")
     into layout.projectDirectory.dir('./src/main/resources/ch/admin/bar/siardsuite/doc')
 }
 
 tasks.named("asciidoctorPdf") { finalizedBy(copyDocumentation)}
-tasks.named("build") { dependsOn(asciidoctorPdf)}
+tasks.named("build") {
+    dependsOn(asciidoctorPdf)
+    dependsOn("plantUml")
+}
+
 tasks.named("processResources") { dependsOn(copyDocumentation)}

docs/sad/sad.adoc

@@ -0,0 +1,91 @@
+// header file for arc42-template,
+// including all help texts
+//
+// ====================================
+
+// configure EN settings for asciidoc
+include::src/config.adoc[]
+
+= image:arc42-logo.png[arc42] Template
+:revnumber: 8.2 EN
+:revdate: January 2023
+:revremark: (based upon AsciiDoc version)
+// toc-title definition MUST follow document title without blank line!
+:toc-title: Table of Contents
+
+//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::src/about-arc42.adoc[]
+
+// horizontal line
+***
+
+
+
+
+// numbering from here on
+:numbered:
+
+<<<<
+// 1. Introduction and Goals
+include::src/01_introduction_and_goals.adoc[]
+
+<<<<
+// 2. Architecture Constraints
+include::src/02_architecture_constraints.adoc[]
+
+<<<<
+// 3. System Scope and Context
+include::src/03_system_scope_and_context.adoc[]
+
+<<<<
+// 4. Solution Strategy
+include::src/04_solution_strategy.adoc[]
+
+<<<<
+// 5. Building Block View
+include::src/05_building_block_view.adoc[]
+
+<<<<
+// 6. Runtime View
+include::src/06_runtime_view.adoc[]
+
+<<<<
+// 7. Deployment View
+include::src/07_deployment_view.adoc[]
+
+<<<<
+// 8. Concepts
+include::src/08_concepts.adoc[]
+
+<<<<
+// 9. Architecture Decisions
+include::src/09_architecture_decisions.adoc[]
+
+<<<<
+// 10. Quality Requirements
+include::src/10_quality_requirements.adoc[]
+
+<<<<
+// 11. Technical Risks
+include::src/11_technical_risks.adoc[]
+
+<<<<
+// 12. Glossary
+include::src/12_glossary.adoc[]
+
+

docs/sad/src/01_introduction_and_goals.adoc

@@ -0,0 +1,56 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-introduction-and-goals]]
+== Introduction and Goals
+
+
+
+=== Requirements Overview
+
+What is SIARD-Suite?
+
+* SIARD Suite is a set of tools for the long-term archiving of data stored in relational databases as SIARD archives.
+* SIARD Suite is the reference implementation of the [SIARD Specification](https://siard.dilcis.eu/SIARD%202.2/SIARD%202.2.pdf)
+
+Main Features:
+
+* Support for multiple relational database management systems.
+* Graphical user interface (GUI) and command line interface (CLI) for archiving and restoring data
+* Clients for Windows, Mac and Linux
+
+=== Quality Goals
+
+[options="header",cols="1,2"]
+|===
+|Quality Goal|Motivation and Description
+| Swiss Federal Archive | -
+| Archives world wide | -
+| Developers/ Contributors | -
+
+|===
+
+=== Stakeholders
+
+[options="header",cols="1,2,2"]
+|===
+|Role/Name|Contact|Expectations
+| Swiss Federal Archive | https://github.com/sfa-siard | Long-term archiving of data sets.<br/>Support for common relational database systems.
+
+Reliable, correct archiving of big data sets
+
+The Software must run given the contstraints on SFA Laptops and Workstations.
+
+Cost efficient maintanance and flexible software
+| Archives world wide | - | Long-term archiving of data sets. Support for common relational database systems.
+
+Reliable, correct archiving of big data sets
+
+Quick Issue handling
+| SIARD Suite users | - | Good User Experience
+Support for a variaty of different DBMS
+| Puzzle ITC GmbH (main contributor| https://github.com/puzzle |
+| Developers, Contributors | - | Modern Java, clean codebase.
+
+Simple setup including a variety of databases with test data
+|
+|===

docs/sad/src/02_architecture_constraints.adoc

@@ -0,0 +1,18 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-architecture-constraints]]
+== Architecture Constraints
+
+=== Technical Constraints
+
+[options="header",cols="1,2"]
+|===
+|Constraint |Explanation, Background
+
+|Must run with Java 8
+|Computers (aka Bundeslaptop) used by the Swiss Federal Archived are managed by the BIT. Users are not allowed to install any software on these machines. The Java Runtime environment is fixed to JRE8 (Corretto) and there is no way for these users to circumvent this restriction.
+|===
+
+
+
+

docs/sad/src/03_system_scope_and_context.adoc

@@ -0,0 +1,43 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-system-scope-and-context]]
+== System Scope and Context
+
+=== Business Context
+
+[mermaid]
+----
+graph LR
+    access[(MS Access)]
+    mssqlserver[(MS SQL Server)]
+    oracle[(Oracle)]
+    postgres[(PostGreSQL)]
+    mysql[(MySQL)]
+    mariadb[(Maria DB)]
+    db2[(IBM DB2)]
+    suite[SIARD Suite]
+    archive[[SIARD Archive]]
+    html[[HTML]]
+
+
+access <--> suite
+mssqlserver <--> suite
+oracle <--> suite
+postgres <--> suite
+mysql <--> suite
+mariadb <--> suite
+db2 <--> suite
+
+suite <--> archive
+suite --> html
+
+----
+
+The Application `SIARD Suite` is able to read data from various database systems in order to create a SIARD Archive file. The application can also read a SIARD Archive and upload it into a database. This is not necessarily the same DBMS as the original data source.
+
+A (somewhat limited) export function allows users to export data from an archive as html files.
+
+
+=== Technical Context
+
+SIARD Suite is a standalone Java Application that runs on Linux, Windows and Mac. The connection to the databases is done using vendor specific JDBC drivers using a jdbc url.

docs/sad/src/04_solution_strategy.adoc

@@ -0,0 +1,7 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-solution-strategy]]
+== Solution Strategy
+
+
+

docs/sad/src/05_building_block_view.adoc

@@ -0,0 +1,76 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-building-block-view]]
+
+
+== Building Block View
+
+=== Whitebox Overall System
+
+[mermaid]
+----
+graph TD
+    siardsuite[SiardSuite]
+    siardapi[SiardApi]
+    siardcmd[SiardCmd]
+    sqlparser[SqlParser]
+    jdbcbase[JdbcBase]
+    jdbcaccess[JdbcAccess]
+    jdbcdb2[JdbcDb2]
+    jdbcoracle[JdbcOracle]
+    jdbcmssql[JdbcMssql]
+    jdbcmysql[JdbcMysql]
+    enterutils[EnterUtils]
+    zip64file[Zip64File]
+
+    siardsuite --- siardapi
+    siardsuite --- siardcmd
+    siardsuite --- sqlparser
+    siardsuite --- zip64file
+    siardsuite --- enterutils
+
+    siardapi --- sqlparser
+    siardapi --- enterutils
+    siardapi --- zip64file
+    zip64file --- enterutils
+    sqlparser --- enterutils
+
+    siardcmd --- siardapi
+    siardcmd --- sqlparser
+    siardcmd --- jdbc
+    siardcmd --- enterutils
+
+    jdbc --- enterutils
+    jdbc --- sqlparser
+
+    subgraph jdbc
+    jdbcaccess --> jdbcbase
+    jdbcdb2 --> jdbcbase
+    jdbcoracle --> jdbcbase
+    jdbcpostgres --> jdbcbase
+    jdbcmssql --> jdbcbase
+    jdbcmysql --> jdbcbase
+    end
+
+----
+
+
+Contained Building Blocks::
+
+[options="header",cols="1,2"]
+|===
+|Module | Repository
+|SiardSuite |
+|SiardApi |
+|SiardCmd |
+|SqlParser |
+|JdbcBase |
+|JdbcAccess |
+|JdbcDb2 |
+|JdbcOracle |
+|JdbcMssql |
+|JdbcMysql |
+|EnterUtils |
+|Zip64File |
+|===
+

docs/sad/src/06_runtime_view.adoc

@@ -0,0 +1,20 @@
+ifndef::imagesdir[:imagesdir: ../images]
+
+[[section-runtime-view]]
+== Runtime View
+
+
+
+
+=== <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.>_
+
+=== <Runtime Scenario 2>
+
+=== ...
+
+=== <Runtime Scenario n>