Add docs

docs/Architecture_documentation/00_Mainpage.dox

@@ -0,0 +1,27 @@
+/*!
+
+\page Chap_00_Architecture_documentation Architecture documentation
+
+This page and its linked pages shall provide the architecture documentation of the library Search Engine.
+
+\section Table_of_contents Table of contents
+
+\subpage Chap_01_Introduction <br>
+\subpage Chap_02_Architectural_constraints <br>
+\subpage Chap_03_System_scope_and_context <br>
+\subpage Chap_04_Solution_strategy <br>
+\subpage Chap_05_Building_block_view <br>
+\subpage Chap_06_Runtime_View <br>
+\subpage Chap_07_Deployment_view <br>
+\subpage Chap_08_Concepts <br>
+\subpage Chap_09_Design_decisions <br>
+\subpage Chap_10_Quality_scenarios <br>
+\subpage Chap_11_Technical_risks <br>
+\subpage Chap_12_Glossary <br>
+
+\section Template_disclosure Template disclosure
+
+The structure of this page and of its linked pages follows the arc42 template by Peter Hruschka and Gernot Starke (please see https://arc42.org for further technical details).
+
+*/
+

docs/Architecture_documentation/01_Introduction.dox

@@ -0,0 +1,102 @@
+/*!
+
+\page Chap_01_Introduction 1 Introduction
+
+\tableofcontents
+
+
+
+Describes the relevant requirements and the driving forces that software architects and development team must consider. These include
+
+<ul>
+  <li> underlying business goals, essential features and functional requirements for the system,
+  <li> quality goals for the architecture,
+  <li> relevant stakeholders and their expectations
+</ul>
+
+\section Chap_01_01_Requirements_Overview 1.1 Requirements Overview
+
+Short description of the functional requirements, driving forces, extract (or abstract) of requirements. Link to (hopefully existing) requirements documents (with version number and information where to find it).
+
+From the point of view of the end users a system is created or modified to improve support of a business activity and/or improve the quality.
+
+\section Chap_01_02_References 1.2 References
+
+<table>
+  <tr>
+    <th>#</th>
+    <th>Reference</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td>XXX</td>
+  </tr>
+  <tr>
+    <td>2</td>
+    <td>XXX</td>
+  </tr>
+</table>
+
+
+\section Chap_01_03_Quality_goals 1.3 Quality goals
+
+Please consult ISO 25010 for an overview.
+
+<ul>
+  <li> Reliability
+  <li> Availability
+  <li> Maintainability
+  <li> Safety
+  <li> Transferability
+  <li> Performance and Efficiency
+  <li> Operability/Usability
+  <li> Security
+  <li> Testability
+  <li> Modifiability
+  <li> Portability
+</ul>
+
+<table>
+  <tr>
+    <th>#</th>
+    <th>Quality</th>
+    <th>Motivation</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td>2</td>
+    <td>3</td>
+  </tr>
+</table>
+
+\section Chap_01_04_Stakeholders 1.4 Stakeholders
+
+Explicit overview of stakeholders of the system, i.e. all person, roles or organizations that
+
+<ul>
+  <li> should know the architecture
+  <li> have to be convinced of the architecture
+  <li> have to work with the architecture or with code
+  <li> need the documentation of the architecture for their work
+  <li> have to come up with decisions about the system or its development
+</ul>
+
+<table>
+  <tr>
+    <th>Role</th>
+    <th>Name</th>
+    <th>Expectations</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td></td>
+    <td>
+      <ul>
+        <li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+*/
+

docs/Architecture_documentation/02_Architectural_constraints.dox

@@ -0,0 +1,63 @@
+/*!
+
+\page Chap_02_Architectural_constraints 2 Architectural Constraints
+
+\tableofcontents
+
+Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies.
+
+Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though.
+
+\section Chap_02_01_Technical_constraints 2.1 Technical constraints
+
+<ul>
+  <li> Hardware
+  <li> Technology
+  <li> Frameworks
+</ul>
+
+<table>
+  <tr>
+    <th>Nr.</th>
+    <th>Constraint</th>
+    <th>Background and/or motivation</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td>2</td>
+    <td>3</td>
+  </tr>
+</table>
+
+\section Chap_02_02_Organisational_constraints 2.2 Organisational constraints
+
+<table>
+  <tr>
+    <th>Nr.</th>
+    <th>Constraint</th>
+    <th>Background and/or motivation</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td>2</td>
+    <td>3</td>
+  </tr>
+</table>
+
+\section Chap_02_03_Conventions 2.3 Conventions
+
+<table>
+  <tr>
+    <th>Nr.</th>
+    <th>Convention</th>
+    <th>Background and/or motivation</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td>2</td>
+    <td>3</td>
+  </tr>
+</table>
+
+*/
+

docs/Architecture_documentation/03_System_scope_and_context.dox

@@ -0,0 +1,26 @@
+/*!
+
+\page Chap_03_System_scope_and_context 3 System Scope and Context 
+
+\tableofcontents
+
+System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
+
+If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).
+
+The domain interfaces and technical interfaces to communication partners are among your system’s most critical aspects. Make sure that you completely understand them.
+
+\section Chap_03_01_Business_context 3.1 Business context
+
+Specification of all communication partners (users, IT-systems, …) with explanations of domain specific inputs and outputs or interfaces. Optionally you can add domain specific formats or communication protocols.
+
+All stakeholders should understand which data are exchanged with the environment of the system.
+
+\section Chap_03_02_Technical_context 3.2 Technical context
+
+Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation with I/O uses which channel.
+
+Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.
+
+*/
+

docs/Architecture_documentation/04_Solution_strategy.dox

@@ -0,0 +1,19 @@
+/*!
+
+\page Chap_04_Solution_strategy 4 Solution strategy
+
+\tableofcontents
+
+A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture. These include
+
+<ul>
+  <li> technology decisions
+  <li> decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or design pattern
+  <li> decisions on how to achieve key quality goals
+  <li> relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to third parties.
+</ul>    
+
+These decisions form the cornerstones for your architecture. They are the basis for many other detailed decisions or implementation rules.
+
+*/
+

docs/Architecture_documentation/05_Building_block_view.dox

@@ -0,0 +1,54 @@
+/*!
+
+\page Chap_05_Building_block_view 5 Building Block View
+
+\tableofcontents
+
+The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, data structures, …) as well as their dependencies (relationships, associations, …)
+
+This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.
+
+Maintain an overview of your source code by making its structure understandable through abstraction.
+
+This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.
+
+
+Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.
+Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.
+Level 3 zooms into selected building blocks of level 2, and so on.
+
+\section Chap_05_01 5.1 XXX
+
+\subsection Chap_05_01_01 5.1.1 XXX
+
+Overview diagram
+
+\subsubsection Chap_05_01_01_01 Responsibility
+
+Describe in one short sentence
+
+\subsubsection Chap_05_01_01_02 Interface 
+
+\subsubsection Chap_05_01_01_03 Decomposition
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Responsibility</th>
+    <th>Reference</th>
+  </tr>
+  <tr>
+    <td>1</td>
+    <td>2</td>
+    <td>3</td>
+  </tr>
+</table>
+
+\subsubsection Chap_05_01_01_04 Reasons for decomposition
+
+<ul>
+  <li>
+</ul>
+
+*/
+

docs/Architecture_documentation/06_Runtime_view.dox

@@ -0,0 +1,20 @@
+/*!
+
+\page Chap_06_Runtime_View 6 Runtime View
+
+\tableofcontents
+
+The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:
+
+<ul>
+  <li> important use cases or features: how do building blocks execute them?
+  <li> interactions at critical external interfaces: how do building blocks cooperate with users and neighbouring systems?
+  <li> operation and administration: launch, start-up, stop error and exception scenarios
+</ul>
+
+Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevancy. It is not important to describe a large number of scenarios. You should rather document a representative selection.
+
+You should understand how (instances of) building blocks of your system perform their job and communicate at runtime. You will mainly capture scenarios in your documentation to communicate your architecture to stakeholders that are less willing or able to read and understand the static models (building block view, deployment view).
+
+*/
+

docs/Architecture_documentation/07_Deployment_view.dox

@@ -0,0 +1,23 @@
+/*!
+
+\page Chap_07_Deployment_view 7 Deployment View
+
+\tableofcontents
+
+The deployment view describes:
+
+<ul>
+  <li> the technical infrastructure used to execute your system, with infrastructure elements like geographical locations, environments, computers, processors, channels and net topologies as well as other infrastructure elements and
+  <li> the mapping of (software) building blocks to that infrastructure elements.
+</ul>
+
+Often systems are executed in different environments, e.g. development environment, test environment, production environment. In such cases you should document all relevant environments.
+
+Especially document the deployment view when your software is executed as distributed system with more than one computer, processor, server or container or when you design and construct your own hardware processors and chips.
+
+From a software perspective it is sufficient to capture those elements of the infrastructure that are needed to show the deployment of your building blocks. Hardware architects can go beyond that and describe the infrastructure to any level of detail they need to capture.
+
+Software does not run without hardware. This underlying infrastructure can and will influence your system and/or some cross-cutting concepts. Therefore, you need to know the infrastructure.
+
+*/
+

docs/Architecture_documentation/08_Concepts.dox

@@ -0,0 +1,24 @@
+/*!
+
+\page Chap_08_Concepts 8 Concepts
+
+\tableofcontents
+
+\section Chap_08_01_Persistency 8.1 Persistency
+
+\section Chap_08_02_User_interface 8.2 User Interface
+
+\section Chap_08_03_Exception_and_error_handling 8.3 Exception/Error Handling
+
+\section Chap_08_04_Logging_tracing 8.4 Logging, tracing
+
+\section Chap_08_05_Configurability 8.5 Configurability
+
+\section Chap_08_06_Internationalization 8.6 Internationalization
+
+\section Chap_08_07_Reusability 8.7 Reusability
+
+\section Chap_08_08_Testability 8.8 Testability
+
+*/
+