Add Arc42

docs/astro.config.mjs

@@ -12,15 +12,8 @@ export default defineConfig({
 			},
 			sidebar: [
 				{
-					label: 'Guides',
-					items: [
-						// Each item here is one entry in the navigation menu.
-						{ label: 'Example Guide', link: '/guides/example/' },
-					],
-				},
-				{
-					label: 'Reference',
-					autogenerate: { directory: 'reference' },
+					label: 'Software Architecture (Arc42)',
+					autogenerate: { directory: 'arc42' },
 				},
 			],
 			editLink: { baseUrl: 'https://github.com/HAW-Rust-SoSe24/gb_emulator/tree/main/docs/' },

docs/src/content/docs/arc42/00. About Arc42.md

@@ -0,0 +1,75 @@
+---
+title: About arc42
+description: Preface to the arc42 documentation template.
+---
+
+# About arc42
+
+arc42, the Template for documentation of software and system
+architecture.
+
+By Dr. Gernot Starke, Dr. Peter Hruschka and contributors.
+
+Template Revision: 7.0 EN (based on asciidoc), January 2017
+
+© We acknowledge that this document uses material from the arc 42
+architecture template, <http://www.arc42.de>. Created by Dr. Peter
+Hruschka & Dr. Gernot Starke.
+
+> **Note**
+>
+> This version of the template contains some help and explanations. It
+> is used for familiarization with arc42 and the understanding of the
+> concepts. For documentation of your own system you use better the
+> *plain* version.  
+
+
+## 1. Introduction and Goals 
+Short description of the requirements, driving forces, extract (or abstract) of requirements. Top three (max five) quality goals for the architecture which have highest priority for the major stakeholders. A table of important stakeholders with their expectation regarding architecture.   
+![Introduction and Goals](images/01-intro-and-goals.png)
+
+
+## 2. Architecture Constraints 
+Anything that constrains teams in design and implementation decisions or decision about related processes. Can sometimes go beyond individual systems and are valid for whole organizations and companies.   
+![Architecture Constraints](images/02-constraints-overview.png)
+
+## 3. Context and scope 
+Delimits your system from its (external) communication partners (neighboring systems and users). Specifies the external interfaces. Shown from a business/domain perspective (always) or a technical perspective (optional).   
+![Context and scope](images/03-context-overview.png)
+
+## 4. Solution Strategy 
+Summary of the fundamental decisions and solution strategies that shape the architecture. Can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions.   
+![Solution Strategy](images/04-solution-strategy-overview.png)
+
+## 5. Building Block View 
+Static decomposition of the system, abstractions of source-code, shown as hierarchy of white boxes (containing black boxes), up to the appropriate level of detail.   
+![Building Block View](images/05-building-block-overview.png)
+
+## 6. Runtime View 
+Behavior of building blocks as scenarios, covering important use cases or features, interactions at critical external interfaces, operation and administration plus error and exception behavior.   
+![Runtime View](images/06-runtime-overview.png)
+
+## 7. Deployment View 
+Technical infrastructure with environments, computers, processors, topologies. Mapping of (software) building blocks to infrastructure elements.    
+![Deployment View](images/07-deployment-overview.png)
+
+## 8. Crosscutting Concepts
+Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architectur patterns and -styles, rules for using specific technology and inmplementation rules.  
+![Crosscutting Concepts](images/08-concepts-overview.png)
+
+## 9. Architecture Decisions 
+Important, expensive, critical, large scale or risky architecture decisions including rationals.   
+![Architecture Decisions](images/09-decision-overview.png)
+
+## 10. Quality Requirements 
+Quality requirements as scenarios, with quality tree to provide high-level overview. The most important quality goals should have been described in section 1.2. (quality goals).     
+![Quality Requirements](images/10-q-scenario-overview.png)
+
+## 11. Risks and Technical Debt 
+Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about?   
+![Risks and Technical Debt](images/11-risk-overview.png)
+
+## 12. Glossary 
+Important domain and technical terms that stakeholders use when discussing he system. Also: translation reference if you work in a multi-language environment.  
+![Risks and Technical Debt](images/12-glossary-overview.png)  
+

docs/src/content/docs/arc42/01. Introduction and Goals.md

@@ -0,0 +1,98 @@
+---
+title: Introduction and Goals
+description: Describes the relevant requirements and the driving forces that software architects and development team must consider.
+---
+
+Introduction and Goals
+======================
+
+Describes the relevant requirements and the driving forces that software
+architects and development team must consider. These include
+
+-   underlying business goals, essential features and functional
+    requirements for the system
+
+-   quality goals for the architecture
+
+-   relevant stakeholders and their expectations
+
+
+Requirements Overview
+---------------------
+
+**Contents.**
+
+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).
+
+**Motivation.**
+
+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.
+
+**Form.**
+
+Short textual description, probably in tabular use-case format. If
+requirements documents exist this overview should refer to these
+documents.
+
+Keep these excerpts as short as possible. Balance readability of this
+document with potential redundancy w.r.t to requirements documents.
+
+Quality Goals
+-------------
+
+**Contents.**
+
+The top three (max five) quality goals for the architecture whose
+fulfillment is of highest importance to the major stakeholders. We
+really mean quality goals for the architecture. Don’t confuse them with
+project goals. They are not necessarily identical.
+
+**Motivation.**
+
+You should know the quality goals of your most important stakeholders,
+since they will influence fundamental architectural decisions. Make sure
+to be very concrete about these qualities, avoid buzzwords. If you as an
+architect do not know how the quality of your work will be judged …
+
+**Form.**
+
+A table with quality goals and concrete scenarios, ordered by priorities
+
+Stakeholders
+------------
+
+**Contents.**
+
+Explicit overview of stakeholders of the system, i.e. all person, roles
+or organizations that
+
+-   should know the architecture
+
+-   have to be convinced of the architecture
+
+-   have to work with the architecture or with code
+
+-   need the documentation of the architecture for their work
+
+-   have to come up with decisions about the system or its development
+
+**Motivation.**
+
+You should know all parties involved in development of the system or
+affected by the system. Otherwise, you may get nasty surprises later in
+the development process. These stakeholders determine the extent and the
+level of detail of your work and its results.
+
+**Form.**
+
+Table with role names, person names, and their expectations with respect
+to the architecture and its documentation.
+
+| Role/Name   | Contact                   | Expectations              |
+| ----------- | ------------------------- | ------------------------- |
+| Role-1      | Contact-1                 | *<Expectation-1*>   |
+| Role-2      | Contact-2                 | *<Expectation-2*>   |

docs/src/content/docs/arc42/02. Architecture Constraints.md

@@ -0,0 +1,27 @@
+---
+title: Architecture Constraints
+description: Describes the constraints that software architects must consider.
+---
+
+Architecture Constraints
+========================
+
+**Contents.**
+
+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.
+
+**Motivation.**
+
+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.
+
+**Form.**
+
+Simple tables of constraints with explanations. If needed you can
+subdivide them into technical constraints, organizational and political
+constraints and conventions (e.g. programming or versioning guidelines,
+documentation or naming conventions)

docs/src/content/docs/arc42/03. Context and scope.md

@@ -0,0 +1,89 @@
+---
+title: System Scope and Context
+description: Delimits your system from all its communication partners (neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
+---
+
+System Scope and Context
+========================
+
+**Contents.**
+
+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).
+
+**Motivation.**
+
+The domain interfaces and technical interfaces to communication partners
+are among your system’s most critical aspects. Make sure that you
+completely understand them.
+
+**Form.**
+
+Various options:
+
+-   Context diagrams
+
+-   Lists of communication partners and their interfaces.
+
+
+Business Context
+----------------
+
+**Contents.**
+
+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.
+
+**Motivation.**
+
+All stakeholders should understand which data are exchanged with the
+environment of the system.
+
+**Form.**
+
+All kinds of diagrams that show the system as a black box and specify
+the domain interfaces to communication partners.
+
+Alternatively (or additionally) you can use a table. The title of the
+table is the name of your system, the three columns contain the name of
+the communication partner, the inputs, and the outputs.
+
+**<Diagram or Table>**
+
+**<optionally: Explanation of external domain interfaces>**
+
+
+Technical Context
+-----------------
+
+**Contents.**
+
+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.
+
+**Motivation.**
+
+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.
+
+**Form.**
+
+E.g. UML deployment diagram describing channels to neighboring systems,
+together with a mapping table showing the relationships between channels
+and input/output.
+
+**<Diagram or Table>**
+
+**<optionally: Explanation of technical interfaces>**
+
+**<Mapping Input/Output to Channels>**

docs/src/content/docs/arc42/04. Solution Strategy.md

@@ -0,0 +1,35 @@
+---
+title: Solution Strategy
+description: A short summary and explanation of the fundamental decisions and solution strategies, that shape the system’s architecture.
+---
+
+Solution Strategy
+=================
+
+**Contents.**
+
+A short summary and explanation of the fundamental decisions and
+solution strategies, that shape the system’s architecture. These include
+
+-   technology decisions
+
+-   decisions about the top-level decomposition of the system, e.g.
+    usage of an architectural pattern or design pattern
+
+-   decisions on how to achieve key quality goals
+
+-   relevant organizational decisions, e.g. selecting a development
+    process or delegating certain tasks to third parties.
+
+**Motivation.**
+
+These decisions form the cornerstones for your architecture. They are
+the basis for many other detailed decisions or implementation rules.
+
+**Form.**
+
+Keep the explanation of these key decisions short.
+
+Motivate what you have decided and why you decided that way, based upon
+your problem statement, the quality goals and key constraints. Refer to
+details in the following sections.