diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..174e0e8c --- /dev/null +++ b/docs/index.html @@ -0,0 +1,1904 @@ + + + + + + + +Template + + + + + +
+
+
+ +
+

About arc42

+
+
+

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

+
+
+

Template Version 8.2 EN. (based upon AsciiDoc version), January 2023

+
+
+

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

+
+
+
+
+
+ + + + + +
+
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 (wiq_es04b)

+
+
+
+
+

Describes the relevant requirements and the driving forces that software architects and development team must consider. +These include

+
+
+
    +
  • +

    underlying business goals,

    +
    • +
  • +

    essential features,

    +
    • +
  • +

    essential functional requirements,

    +
    • +
  • +

    quality goals for the architecture and

    +
    • +
  • +

    relevant stakeholders and their expectations

    +
    • +
+
+
+
+
+

1.1. 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.

+
+
+
Further Information
+

See Introducdction and Goals in the arc42 documentation.

+
+
+
+
+
+

1.2. 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.

+
+
+

Consider this overview of potential topics (based upon the ISO 25010 standard):

+
+
+
+Categories of Quality Requirements +
+
+
+
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

+
+
+
+
+
+

1.3. 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/NameContactExpectations

<Role-1>

<Contact-1>

<Expectation-1>

<Role-2>

<Contact-2>

<Expectation-2>

+
+
+
+
+
+

2. Architecture Constraints

+
+
+
+
+
Contents
+

Any requirement that constraints 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)

+
+
+
Further Information
+

See Architecture Constraints in the arc42 documentation.

+
+
+
+
+
    +
  • +

    Programming Language Restriction: +The system must be implemented using Java as the primary programming language.

    +
    • +
  • +

    Mandatory Usage of WikiData API: +The WikiData API must be utilized as an integral part of the system, and interactions with WikiData are obligatory for data retrieval and integration.

    +
    • +
  • +

    Web Frontend Requirement: +The system must include at least one web frontend, and it is mandatory for deployment.

    +
    • +
  • +

    Freedom in Database Selection: +There are no imposed restrictions on the choice of the database. Teams have the freedom to select a suitable database technology based on project requirements.

    +
    • +
  • +

    No Company Policy Constraints: +There are no specific constraints or restrictions related to company policies. Teams have the flexibility to make decisions aligned with project goals.

    +
    • +
+
+
+
+
+
+

3. 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.

    +
    • +
+
+
+
Further Information
+

See Context and Scope in the arc42 documentation.

+
+
+
+
+

3.1. 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>

+
+
+
+

3.2. 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 which 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>

+
+
+
+
+
+
+

4. Solution Strategy

+
+
+
+
+
Contents
+

A short summary and explanation of the fundamental decisions and solution strategies, that shape system architecture. It includes

+
+
+
    +
  • +

    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 foundation for many other detailed decisions or implementation rules.

+
+
+
Form
+

Keep the explanations of such key decisions short.

+
+
+

Motivate what was decided and why it was decided that way, +based upon problem statement, quality goals and key constraints. +Refer to details in the following sections.

+
+
+
Further Information
+

See Solution Strategy in the arc42 documentation.

+
+
+
+
+
+
+
+

5. Building Block View

+
+
+
+
+
Content
+

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.

+
+
+
Motivation
+

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.

+
+
+
Form
+

The building block view is a hierarchical collection of black boxes and white boxes +(see figure below) and their descriptions.

+
+
+
+Hierarchy of building blocks +
+
+
+

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.

+
+
+
Further Information
+

See Building Block View in the arc42 documentation.

+
+
+
+
+

5.1. Whitebox Overall System

+
+
+
+

Here you describe the decomposition of the overall system using the following white box template. It contains

+
+
+
    +
  • +

    an overview diagram

    +
    • +
  • +

    a motivation for the decomposition

    +
    • +
  • +

    black box descriptions of the contained building blocks. For these we offer you alternatives:

    +
    +
      +
    • +

      use one table for a short and pragmatic overview of all contained building blocks and their interfaces

      +
      • +
    • +

      use a list of black box descriptions of the building blocks according to the black box template (see below). +Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).

      +
      • +
    +
    +
    • +
  • +

    (optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. +Since there are so many ways to specify interfaces why do not provide a specific template for them. + In the worst case you have to specify and describe syntax, semantics, protocols, error handling, + restrictions, versions, qualities, necessary compatibilities and many things more. +In the best case you will get away with examples or simple signatures.

    +
    • +
+
+
+
+
+

<Overview Diagram>

+
+
+
+
Motivation
+
+

<text explanation>

+
+
Contained Building Blocks
+
+

<Description of contained building block (black boxes)>

+
+
Important Interfaces
+
+

<Description of important interfaces>

+
+
+
+
+
+
+

Insert your explanations of black boxes from level 1:

+
+
+

If you use tabular form you will only describe your black boxes with name and +responsibility according to the following schema:

+
+ ++++ + + + + + + + + + + + + + + + + +
NameResponsibility

<black box 1>

 <Text>

<black box 2>

 <Text>

+
+

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . +Its headline is the name of the black box.

+
+
+
+
+

5.1.1. <Name black box 1>

+
+
+
+

Here you describe <black box 1> +according the the following black box template:

+
+
+
    +
  • +

    Purpose/Responsibility

    +
    • +
  • +

    Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.

    +
    • +
  • +

    (Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, …​.

    +
    • +
  • +

    (Optional) directory/file location

    +
    • +
  • +

    (Optional) Fulfilled requirements (if you need traceability to requirements).

    +
    • +
  • +

    (Optional) Open issues/problems/risks

    +
    • +
+
+
+
+
+

<Purpose/Responsibility>

+
+
+

<Interface(s)>

+
+
+

<(Optional) Quality/Performance Characteristics>

+
+
+

<(Optional) Directory/File Location>

+
+
+

<(Optional) Fulfilled Requirements>

+
+
+

<(optional) Open Issues/Problems/Risks>

+
+
+
+

5.1.2. <Name black box 2>

+
+

<black box template>

+
+
+
+

5.1.3. <Name black box n>

+
+

<black box template>

+
+
+
+

5.1.4. <Name interface 1>

+
+

…​

+
+
+
+

5.1.5. <Name interface m>

+ +
+
+
+

5.2. Level 2

+
+
+
+

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

+
+
+

You have to decide which building blocks of your system are important enough to justify such a detailed description. +Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. +Leave out normal, simple, boring or standardized parts of your system

+
+
+
+
+

5.2.1. White Box <building block 1>

+
+
+
+

…​describes the internal structure of building block 1.

+
+
+
+
+

<white box template>

+
+
+
+

5.2.2. White Box <building block 2>

+
+

<white box template>

+
+
+

…​

+
+
+
+

5.2.3. White Box <building block m>

+
+

<white box template>

+
+
+
+
+

5.3. Level 3

+
+
+
+

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

+
+
+

When you need more detailed levels of your architecture please copy this +part of arc42 for additional levels.

+
+
+
+
+

5.3.1. White Box <_building block x.1_>

+
+
+
+

Specifies the internal structure of building block x.1.

+
+
+
+
+

<white box template>

+
+
+
+

5.3.2. White Box <_building block x.2_>

+
+

<white box template>

+
+
+
+

5.3.3. White Box <_building block y.1_>

+
+

<white box template>

+
+
+
+
+
+
+
+

6. Runtime View

+
+
+
+
+
Contents
+

The runtime view describes concrete behavior and interactions of the system’s building blocks in form of scenarios from the following areas:

+
+
+
    +
  • +

    important use cases or features: how do building blocks execute them?

    +
    • +
  • +

    interactions at critical external interfaces: how do building blocks cooperate with users and neighboring systems?

    +
    • +
  • +

    operation and administration: launch, start-up, stop

    +
    • +
  • +

    error and exception scenarios

    +
    • +
+
+
+

Remark: The main criterion for the choice of possible scenarios (sequences, workflows) is their architectural relevance. It is not important to describe a large number of scenarios. You should rather document a representative selection.

+
+
+
Motivation
+

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).

+
+
+
Form
+

There are many notations for describing scenarios, e.g.

+
+
+
    +
  • +

    numbered list of steps (in natural language)

    +
    • +
  • +

    activity diagrams or flow charts

    +
    • +
  • +

    sequence diagrams

    +
    • +
  • +

    BPMN or EPCs (event process chains)

    +
    • +
  • +

    state machines

    +
    • +
  • +

    …​

    +
    • +
+
+
+
Further Information
+

See Runtime View in the arc42 documentation.

+
+
+
+
+

6.1. <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.>

    +
    • +
+
+
+

It is possible to use a sequence diagram:

+
+
+
+
actor Alice
+actor Bob
+database Pod as "Bob's Pod"
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+Alice  --> Pod: Store route
+Alice -> Bob: Another authentication Request
+Alice <-- Bob: another authentication Response
+
+
+
+
+

6.2. <Runtime Scenario 2>

+ +
+
+

6.3. …​

+ +
+
+

6.4. <Runtime Scenario n>

+
+
+
+
+
+

7. Deployment View

+
+
+
+
+
Content
+

The deployment view describes:

+
+
+
    +
  1. +

    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

    +
    2. +
  2. +

    mapping of (software) building blocks to that infrastructure elements.

    +
    3. +
+
+
+

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 a deployment view if 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 only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture.

+
+
+
Motivation
+

Software does not run without hardware. +This underlying infrastructure can and will influence a system and/or some +cross-cutting concepts. Therefore, there is a need to know the infrastructure.

+
+
+
Form
+

Maybe a highest level deployment diagram is already contained in section 3.2. as +technical context with your own infrastructure as ONE black box. In this section one can +zoom into this black box using additional deployment diagrams:

+
+
+
    +
  • +

    UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, +when your infrastructure is more complex.

    +
    • +
  • +

    When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure.

    +
    • +
+
+
+
Further Information
+

See Deployment View in the arc42 documentation.

+
+
+
+
+

7.1. Infrastructure Level 1

+
+
+
+

Describe (usually in a combination of diagrams, tables, and text):

+
+
+
    +
  • +

    distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them

    +
    • +
  • +

    important justifications or motivations for this deployment structure

    +
    • +
  • +

    quality and/or performance features of this infrastructure

    +
    • +
  • +

    mapping of software artifacts to elements of this infrastructure

    +
    • +
+
+
+

For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments.

+
+
+
+
+

<Overview Diagram>

+
+
+
+
Motivation
+
+

<explanation in text form>

+
+
Quality and/or Performance Features
+
+

<explanation in text form>

+
+
Mapping of Building Blocks to Infrastructure
+
+

<description of the mapping>

+
+
+
+
+
+

7.2. Infrastructure Level 2

+
+
+
+

Here you can include the internal structure of (some) infrastructure elements from level 1.

+
+
+

Please copy the structure from level 1 for each selected element.

+
+
+
+
+

7.2.1. <Infrastructure Element 1>

+
+

<diagram + explanation>

+
+
+
+

7.2.2. <Infrastructure Element 2>

+
+

<diagram + explanation>

+
+
+

…​

+
+
+
+

7.2.3. <Infrastructure Element n>

+
+

<diagram + explanation>

+
+
+
+
+
+
+
+

8. Cross-cutting Concepts

+
+
+
+
+
Content
+

This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. +Such concepts are often related to multiple building blocks. +They can include many different topics, such as

+
+
+
    +
  • +

    models, especially domain models

    +
    • +
  • +

    architecture or design patterns

    +
    • +
  • +

    rules for using specific technology

    +
    • +
  • +

    principal, often technical decisions of an overarching (= cross-cutting) nature

    +
    • +
  • +

    implementation rules

    +
    • +
+
+
+
Motivation
+

Concepts form the basis for conceptual integrity (consistency, homogeneity) of the architecture. +Thus, they are an important contribution to achieve inner qualities of your system.

+
+
+

Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety.

+
+
+
Form
+

The form can be varied:

+
+
+
    +
  • +

    concept papers with any kind of structure

    +
    • +
  • +

    cross-cutting model excerpts or scenarios using notations of the architecture views

    +
    • +
  • +

    sample implementations, especially for technical concepts

    +
    • +
  • +

    reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping)

    +
    • +
+
+
+
Structure
+

A potential (but not mandatory) structure for this section could be:

+
+
+
    +
  • +

    Domain concepts

    +
    • +
  • +

    User Experience concepts (UX)

    +
    • +
  • +

    Safety and security concepts

    +
    • +
  • +

    Architecture and design patterns

    +
    • +
  • +

    "Under-the-hood"

    +
    • +
  • +

    development concepts

    +
    • +
  • +

    operational concepts

    +
    • +
+
+
+

Note: it might be difficult to assign individual concepts to one specific topic +on this list.

+
+
+
+Possible topics for crosscutting concepts +
+
+
+
Further Information
+

See Concepts in the arc42 documentation.

+
+
+
+
+

8.1. <Concept 1>

+
+

<explanation>

+
+
+
+

8.2. <Concept 2>

+
+

<explanation>

+
+
+

…​

+
+
+
+

8.3. <Concept n>

+
+

<explanation>

+
+
+
+
+
+
+

9. Architecture Decisions

+
+
+
+
+
Contents
+

Important, expensive, large scale or risky architecture decisions including rationales. +With "decisions" we mean selecting one alternative based on given criteria.

+
+
+

Please use your judgement to decide whether an architectural decision should be documented +here in this central section or whether you better document it locally +(e.g. within the white box template of one building block).

+
+
+

Avoid redundancy. +Refer to section 4, where you already captured the most important decisions of your architecture.

+
+
+
Motivation
+

Stakeholders of your system should be able to comprehend and retrace your decisions.

+
+
+
Form
+

Various options:

+
+
+
    +
  • +

    ADR (Documenting Architecture Decisions) for every important decision

    +
    • +
  • +

    List or table, ordered by importance and consequences or:

    +
    • +
  • +

    more detailed in form of separate sections per decision

    +
    • +
+
+
+
Further Information
+

See Architecture Decisions in the arc42 documentation. +There you will find links and examples about ADR.

+
+
+
+
+
+
+
+

10. Quality Requirements

+
+
+
+
+
Content
+

This section contains all quality requirements as quality tree with scenarios. The most important ones have already been described in section 1.2. (quality goals)

+
+
+

Here you can also capture quality requirements with lesser priority, +which will not create high risks when they are not fully achieved.

+
+
+
Motivation
+

Since quality requirements will have a lot of influence on architectural +decisions you should know for every stakeholder what is really important to them, +concrete and measurable.

+
+
+
Further Information
+

See Quality Requirements in the arc42 documentation.

+
+
+
+
+

10.1. Quality Tree

+
+
+
+
Content
+

The quality tree (as defined in ATAM – Architecture Tradeoff Analysis Method) with quality/evaluation scenarios as leafs.

+
+
+
Motivation
+

The tree structure with priorities provides an overview for a sometimes large number of quality requirements.

+
+
+
Form
+

The quality tree is a high-level overview of the quality goals and requirements:

+
+
+
    +
  • +

    tree-like refinement of the term "quality". Use "quality" or "usefulness" as a root

    +
    • +
  • +

    a mind map with quality categories as main branches

    +
    • +
+
+
+

In any case the tree should include links to the scenarios of the following section.

+
+
+
+
+
+

10.2. Quality Scenarios

+
+
+
+
Contents
+

Concretization of (sometimes vague or implicit) quality requirements using (quality) scenarios.

+
+
+

These scenarios describe what should happen when a stimulus arrives at the system.

+
+
+

For architects, two kinds of scenarios are important:

+
+
+
    +
  • +

    Usage scenarios (also called application scenarios or use case scenarios) describe the system’s runtime reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or performance. Example: The system reacts to a user’s request within one second.

    +
    • +
  • +

    Change scenarios describe a modification of the system or of its immediate environment. Example: Additional functionality is implemented or requirements for a quality attribute change.

    +
    • +
+
+
+
Motivation
+

Scenarios make quality requirements concrete and allow to +more easily measure or decide whether they are fulfilled.

+
+
+

Especially when you want to assess your architecture using methods like +ATAM you need to describe your quality goals (from section 1.2) +more precisely down to a level of scenarios that can be discussed and evaluated.

+
+
+
Form
+

Tabular or free form text.

+
+
+
+
+
+
+
+
+

11. Risks and Technical Debts

+
+
+
+
+
Contents
+

A list of identified technical risks or technical debts, ordered by priority

+
+
+
Motivation
+

“Risk management is project management for grown-ups” (Tim Lister, Atlantic Systems Guild.)

+
+
+

This should be your motto for systematic detection and evaluation of risks and technical debts in the architecture, which will be needed by management stakeholders (e.g. project managers, product owners) as part of the overall risk analysis and measurement planning.

+
+
+
Form
+

List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts.

+
+
+
Further Information
+

See Risks and Technical Debt in the arc42 documentation.

+
+
+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PriorityRisk/DebtDescription

High

Migration to Java

+

migration from the current project language, JavaScript (JS), to Java

+

Medium

IDE Configuration

+

Version compatibility, extensions and other preferences to work perfectly without conflicts

+

Medium

Database

+

discuss which database is best for the project

+

Low

Docker

+

Know how docker works, what it is for, how it is used and what its alternatives could be.

+

Low

Microservices

+

Research about microservices and what they can contribute to the project

+
+
+
+
+
+

12. Glossary

+
+
+
+
+
Contents
+

The most important domain and technical terms that your stakeholders use when discussing the system.

+
+
+

You can also see the glossary as source for translations if you work in multi-language teams.

+
+
+
Motivation
+

You should clearly define your terms, so that all stakeholders

+
+
+
    +
  • +

    have an identical understanding of these terms

    +
    • +
  • +

    do not use synonyms and homonyms

    +
    • +
+
+
+
Form
+

A table with columns <Term> and <Definition>.

+
+
+

Potentially more columns in case you need translations.

+
+
+
Further Information
+

See Glossary in the arc42 documentation.

+
+
+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TermDefinition

wikiData

A collaborative platform that provides structured data for Wikimedia projects, including Wikipedia.

IDE (Integrated Development Environment)

A software application that provides comprehensive facilities to programmers for software development.

Docker

An open-source platform designed to automate the deployment of applications inside lightweight, portable containers.

Microservices

An architectural style that structures an application as a collection of small, independent services.

API (Application Programming Interface)

A set of protocols and tools for building software applications, allowing them to communicate with each other.

+
+
+
+ + + \ No newline at end of file diff --git a/docs/package-lock.json b/docs/package-lock.json index ab1646f2..ae39a379 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -1,11 +1,10 @@ { "name": "docs", "version": "1.0.0", - "lockfileVersion": 3, + "lockfileVersion": 2, "requires": true, "packages": { "": { - "name": "docs", "version": "1.0.0", "dependencies": { "gh-pages": "^3.2.3", @@ -540,5 +539,390 @@ "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==" } + }, + "dependencies": { + "array-union": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-1.0.2.tgz", + "integrity": "sha512-Dxr6QJj/RdU/hCaBjOfxW+q6lyuVE6JFWIrAUpuOOhoJJoQ99cUn3igRaHVB5P9WrgFVN0FfArM3x0cueOU8ng==", + "requires": { + "array-uniq": "^1.0.1" + } + }, + "array-uniq": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/array-uniq/-/array-uniq-1.0.3.tgz", + "integrity": "sha512-MNha4BWQ6JbwhFhj03YK552f7cb3AzoE8SzeljgChvL1dl3IcvggXVz1DilzySZkCja+CXuZbdW7yATchWn8/Q==" + }, + "async": { + "version": "2.6.4", + "resolved": "https://registry.npmjs.org/async/-/async-2.6.4.tgz", + "integrity": "sha512-mzo5dfJYwAn29PeiJ0zvwTo04zj8HDJj0Mn8TD7sno7q12prdbnasKJHhkm2c1LgrhlJ0teaea8860oxi51mGA==", + "requires": { + "lodash": "^4.17.14" + } + }, + "balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" + }, + "brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "requires": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==" + }, + "commondir": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz", + "integrity": "sha512-W9pAhw0ja1Edb5GVdIF1mjZw/ASI0AlShXM83UUGe2DVr5TdAPEA1OA8m/g8zWp9x6On7gqufY+FatDbC3MDQg==" + }, + "concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==" + }, + "email-addresses": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/email-addresses/-/email-addresses-3.1.0.tgz", + "integrity": "sha512-k0/r7GrWVL32kZlGwfPNgB2Y/mMXVTq/decgLczm/j34whdaspNrZO8CnXPf1laaHxI6ptUlsnAxN+UAPw+fzg==" + }, + "escape-string-regexp": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz", + "integrity": "sha512-vbRorB5FUQWvla16U8R/qgaFIya2qGzwDrNmCZuYKrbdSUMG6I1ZCGQRefkRVhuOkIGVne7BQ35DSfo1qvJqFg==" + }, + "filename-reserved-regex": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/filename-reserved-regex/-/filename-reserved-regex-2.0.0.tgz", + "integrity": "sha512-lc1bnsSr4L4Bdif8Xb/qrtokGbq5zlsms/CYH8PP+WtCkGNF65DPiQY8vG3SakEdRn8Dlnm+gW/qWKKjS5sZzQ==" + }, + "filenamify": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/filenamify/-/filenamify-4.3.0.tgz", + "integrity": "sha512-hcFKyUG57yWGAzu1CMt/dPzYZuv+jAJUT85bL8mrXvNe6hWj6yEHEc4EdcgiA6Z3oi1/9wXJdZPXF2dZNgwgOg==", + "requires": { + "filename-reserved-regex": "^2.0.0", + "strip-outer": "^1.0.1", + "trim-repeated": "^1.0.0" + } + }, + "find-cache-dir": { + "version": "3.3.2", + "resolved": "https://registry.npmjs.org/find-cache-dir/-/find-cache-dir-3.3.2.tgz", + "integrity": "sha512-wXZV5emFEjrridIgED11OoUKLxiYjAcqot/NJdAkOhlJ+vGzwhOAfcG5OX1jP+S0PcjEn8bdMJv+g2jwQ3Onig==", + "requires": { + "commondir": "^1.0.1", + "make-dir": "^3.0.2", + "pkg-dir": "^4.1.0" + } + }, + "find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "requires": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + } + }, + "fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "requires": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, + "fs.realpath": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", + "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==" + }, + "function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==" + }, + "gh-pages": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/gh-pages/-/gh-pages-3.2.3.tgz", + "integrity": "sha512-jA1PbapQ1jqzacECfjUaO9gV8uBgU6XNMV0oXLtfCX3haGLe5Atq8BxlrADhbD6/UdG9j6tZLWAkAybndOXTJg==", + "requires": { + "async": "^2.6.1", + "commander": "^2.18.0", + "email-addresses": "^3.0.1", + "filenamify": "^4.3.0", + "find-cache-dir": "^3.3.1", + "fs-extra": "^8.1.0", + "globby": "^6.1.0" + } + }, + "glob": { + "version": "7.2.3", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", + "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==", + "requires": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.1.1", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + } + }, + "globby": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-6.1.0.tgz", + "integrity": "sha512-KVbFv2TQtbzCoxAnfD6JcHZTYCzyliEaaeM/gH8qQdkKr5s0OP9scEgvdcngyk7AVdY6YVW/TJHd+lQ/Df3Daw==", + "requires": { + "array-union": "^1.0.1", + "glob": "^7.0.3", + "object-assign": "^4.0.1", + "pify": "^2.0.0", + "pinkie-promise": "^2.0.0" + } + }, + "graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==" + }, + "hasown": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.0.tgz", + "integrity": "sha512-vUptKVTpIJhcczKBbgnS+RtcuYMB8+oNzPK2/Hp3hanz8JmpATdmmgLgSaadVREkDm+e2giHwY3ZRkyjSIDDFA==", + "requires": { + "function-bind": "^1.1.2" + } + }, + "inflight": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", + "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==", + "requires": { + "once": "^1.3.0", + "wrappy": "1" + } + }, + "inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==" + }, + "interpret": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/interpret/-/interpret-1.4.0.tgz", + "integrity": "sha512-agE4QfB2Lkp9uICn7BAqoscw4SZP9kTE2hxiFI3jBPmXJfdqiahTbUuKGsMoN2GtqL9AxhYioAcVvgsb1HvRbA==" + }, + "is-core-module": { + "version": "2.13.1", + "resolved": "https://registry.npmjs.org/is-core-module/-/is-core-module-2.13.1.tgz", + "integrity": "sha512-hHrIjvZsftOsvKSn2TRYl63zvxsgE0K+0mYMoH6gD4omR5IWB2KynivBQczo3+wF1cCkjzvptnI9Q0sPU66ilw==", + "requires": { + "hasown": "^2.0.0" + } + }, + "jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "requires": { + "graceful-fs": "^4.1.6" + } + }, + "locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "requires": { + "p-locate": "^4.1.0" + } + }, + "lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==" + }, + "make-dir": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz", + "integrity": "sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==", + "requires": { + "semver": "^6.0.0" + } + }, + "minimatch": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", + "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", + "requires": { + "brace-expansion": "^1.1.7" + } + }, + "minimist": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz", + "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==" + }, + "object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==" + }, + "once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "requires": { + "wrappy": "1" + } + }, + "p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "requires": { + "p-try": "^2.0.0" + } + }, + "p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "requires": { + "p-limit": "^2.2.0" + } + }, + "p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==" + }, + "path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==" + }, + "path-is-absolute": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", + "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==" + }, + "path-parse": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz", + "integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==" + }, + "pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==" + }, + "pinkie": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/pinkie/-/pinkie-2.0.4.tgz", + "integrity": "sha512-MnUuEycAemtSaeFSjXKW/aroV7akBbY+Sv+RkyqFjgAe73F+MR0TBWKBRDkmfWq/HiFmdavfZ1G7h4SPZXaCSg==" + }, + "pinkie-promise": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/pinkie-promise/-/pinkie-promise-2.0.1.tgz", + "integrity": "sha512-0Gni6D4UcLTbv9c57DfxDGdr41XfgUjqWZu492f0cIGr16zDU06BWP/RAEvOuo7CQ0CNjHaLlM59YJJFm3NWlw==", + "requires": { + "pinkie": "^2.0.0" + } + }, + "pkg-dir": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/pkg-dir/-/pkg-dir-4.2.0.tgz", + "integrity": "sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ==", + "requires": { + "find-up": "^4.0.0" + } + }, + "rechoir": { + "version": "0.6.2", + "resolved": "https://registry.npmjs.org/rechoir/-/rechoir-0.6.2.tgz", + "integrity": "sha512-HFM8rkZ+i3zrV+4LQjwQ0W+ez98pApMGM3HUrN04j3CqzPOzl9nmP15Y8YXNm8QHGv/eacOVEjqhmWpkRV0NAw==", + "requires": { + "resolve": "^1.1.6" + } + }, + "resolve": { + "version": "1.22.8", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.8.tgz", + "integrity": "sha512-oKWePCxqpd6FlLvGV1VU0x7bkPmmCNolxzjMf4NczoDnQcIWrAF+cPtZn5i6n+RfD2d9i0tzpKnG6Yk168yIyw==", + "requires": { + "is-core-module": "^2.13.0", + "path-parse": "^1.0.7", + "supports-preserve-symlinks-flag": "^1.0.0" + } + }, + "semver": { + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==" + }, + "shelljs": { + "version": "0.8.5", + "resolved": "https://registry.npmjs.org/shelljs/-/shelljs-0.8.5.tgz", + "integrity": "sha512-TiwcRcrkhHvbrZbnRcFYMLl30Dfov3HKqzp5tO5b4pt6G/SezKcYhmDg15zXVBswHmctSAQKznqNW2LO5tTDow==", + "requires": { + "glob": "^7.0.0", + "interpret": "^1.0.0", + "rechoir": "^0.6.2" + } + }, + "shx": { + "version": "0.3.4", + "resolved": "https://registry.npmjs.org/shx/-/shx-0.3.4.tgz", + "integrity": "sha512-N6A9MLVqjxZYcVn8hLmtneQWIJtp8IKzMP4eMnx+nqkvXoqinUPCbUFLp2UcWTEIUONhlk0ewxr/jaVGlc+J+g==", + "requires": { + "minimist": "^1.2.3", + "shelljs": "^0.8.5" + } + }, + "strip-outer": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/strip-outer/-/strip-outer-1.0.1.tgz", + "integrity": "sha512-k55yxKHwaXnpYGsOzg4Vl8+tDrWylxDEpknGjhTiZB8dFRU5rTo9CAzeycivxV3s+zlTKwrs6WxMxR95n26kwg==", + "requires": { + "escape-string-regexp": "^1.0.2" + } + }, + "supports-preserve-symlinks-flag": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz", + "integrity": "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==" + }, + "trim-repeated": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/trim-repeated/-/trim-repeated-1.0.0.tgz", + "integrity": "sha512-pkonvlKk8/ZuR0D5tLW8ljt5I8kmxp2XKymhepUeOdCEfKpZaktSArkLHZt76OB1ZvO9bssUsDty4SWhLvZpLg==", + "requires": { + "escape-string-regexp": "^1.0.2" + } + }, + "universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==" + }, + "wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==" + } } } diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index f4bf1b52..10d47910 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -2,7 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-introduction-and-goals]] == Introduction and Goals (wiq_es04b) - [role="arc42help"] **** Describes the relevant requirements and the driving forces that software architects and development team must consider. @@ -14,9 +13,14 @@ These include * quality goals for the architecture and * relevant stakeholders and their expectations **** +WIQ es un juego desarrollado por HappySw para: -=== Requirements Overview +* Desafiar a los fans de "Saber y ganar" +* Aprender a realizar trabajos en equipo +* Aprobar la asignatura de "Arquitectura del SW" +* Mejorar como ingenieros del software +=== Requirements Overview [role="arc42help"] **** .Contents @@ -37,9 +41,23 @@ Keep these excerpts as short as possible. Balance readability of this document w .Further Information -See https://docs.arc42.org/section-1/[Introduction and Goals] in the arc42 documentation. +See https://docs.arc42.org/section-1/[Introducdction and Goals] in the arc42 documentation. **** +Esta aplicacion web inspirada en el famoso programa español "Saber y ganar" consiste en un minijuego de preguntas y respuestas +en el cual se le pregunta al jugador una precunta y se la ofrecen 4 posibles respuestas de las cuales solo una es la correcta. + +* El jugador deberá registrarse con un nombre +* El jugador deberá responder a la pregunta en un tiempo límite +* Si no responde se le contara como respuesta erronea +* Cada respuesta correcta otorga puntos +* Opcional, se podra guardar la puntuación en un ranking + +Para todos aquellos televidentes de "Saber y ganar" que querian participar en el programa, esta aplicacion es la idonea para +probar su conocimiento. + +La aplicación genera las preguntas automáticamente con la ayuda de Wikidata (la página que da soporte a wikipedia y muchas otras wikias) +para así tener constantemente actualizadas las preguntas en lugar de almacenarlas en una base de datos. === Quality Goals @@ -63,6 +81,14 @@ If you as an architect do not know how the quality of your work will be judged.. A table with quality goals and concrete scenarios, ordered by priorities **** +[options="header",cols="1,2,2"] +|=== +|Nº|Atributo|Motivacion +| 1 | Eficiencia | El acceso, creación de preguntas y desplazamiento entre ellas deberá ser rápido para garantizar satisfacción del usuario. +| 2 | Usabilidad | La aplicación deberá ser atractiva para todo público fan del programa original además de aportar una gran variedad en las preguntas. +| 3 | Mantenimiento | La aplicación deberá garantizar su fácil ampliación y modificación para otorgar nuevas características a los usuarios +|=== + === Stakeholders [role="arc42help"] @@ -85,9 +111,11 @@ These stakeholders determine the extent and the level of detail of your work and Table with role names, person names, and their expectations with respect to the architecture and its documentation. **** -[options="header",cols="1,2,2"] +[options="header",cols="1,2"] |=== -|Role/Name|Contact|Expectations -| __ | __ | __ -| __ | __ | __ +|Role/Name|Expectations +| HappySw | Empresa desarrolladora de la palicación que quiere ganar dinero con su desarrollo y reconocimiento a nivel español +| RTVE | Cadena de television española que contrató el desarrollo para promocionar su programa +| Alumnos uniovi | Desarrolladores de la aplicacion que quieren aprobar la asignatura +| Profesores de ArquiSoft | Evaluadores del desarrollo del programa y version final que quieren aprobar a sus alumnos |=== diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 226e501f..070d697c 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -25,3 +25,19 @@ conventions (e.g. programming or versioning guidelines, documentation or naming See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation. **** + + +- *Programming Language Restriction:* + The system must be implemented using Java as the primary programming language. + +- *Mandatory Usage of WikiData API:* + The WikiData API must be utilized as an integral part of the system, and interactions with WikiData are obligatory for data retrieval and integration. + +- *Web Frontend Requirement:* + The system must include at least one web frontend, and it is mandatory for deployment. + +- *Freedom in Database Selection:* + There are no imposed restrictions on the choice of the database. Teams have the freedom to select a suitable database technology based on project requirements. + +- *No Company Policy Constraints:* + There are no specific constraints or restrictions related to company policies. Teams have the flexibility to make decisions aligned with project goals. diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c528e907..009d85f2 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -31,6 +31,7 @@ See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentat === Business Context + [role="arc42help"] **** .Contents @@ -48,9 +49,25 @@ The title of the table is the name of your system, the three columns contain the **** -**** - -**** +[plantuml,"Deployment diagram",png] +---- + actor user + component System[ + <> + QuestionGame + ] + component WikiData + database Database + + user --> System + System --> Database + System --> WikiData +---- + +* **User:** Represents users who interact with the application to play games or view their history. +* **System (QuestionGame):** The main system that hosts the game logic and manages user interactions. +* **WikiData:** Component used to retrieve data from Wikidata and automatically generate questions. +* **Database:** Stores system information, such as user data, generated questions, game history, etc. === Technical Context @@ -68,8 +85,54 @@ together with a mapping table showing the relationships between channels and inp **** -**** - -**** - -**** +[plantuml,"Technical Context Diagram",png] +---- + + actor user + actor developer + database Database + + node "Question Generation"{ + [WikiData] + } + + node "User Agent" { + [Web / Mobile] + } + + node "QuestionGame server" { + [Frontend] + [QuestionGame] + [User's API] + [Question's API] + } + + user --> [Web / Mobile] + [Web / Mobile] --> (Frontend): HTTPS + [Frontend] --> (QuestionGame): To decide + [QuestionGame] --> Database: Specific driver + [QuestionGame] --> WikiData: HTTP + [QuestionGame] <-- (User's API): To decide + [QuestionGame] <-- (Question's API): To decide + developer --> (User's API) : HTTPS + developer --> (Question's API) : HTTPS +---- + +* **User Agent:** Represents the web or mobile interface used by users. +* **QuestionGame server:** The server-side components, including the Frontend, QuestionGame logic, User's API, and Question's API. +* **HTTPS:** Represents the communication channels, with HTTPS being the protocol used for secure communication. +* **Question Generation:** Represents the means used for question and answers generation. +* **Database:** Represents whichever system used for data persistence. +* **To be decided:** Indicates that specific details about the channels and protocols are yet to be determined. + +==== Input/Output Mapping Table + +[options="header",cols="1,2,2"] +|=== +|Component|Input/Output|Channel/Protocol +| User's API| User registration, game history| HTTPS +| Question's API| Question data retrieval| HTTPS +| Frontend| User interactions, game display| HTTPS +| Database| User data, game history, questions| Specific database driver +| WikiData| Data for question generation| HTTP +|=== \ No newline at end of file diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index 7bf03f7a..a6b94242 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -30,3 +30,18 @@ Refer to details in the following sections. See https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation. **** + +=== Technological Decisions +Programming Language: [Language] will be used for system development due to [reasons]. +Frontend Framework: [Framework] will be adopted for frontend development due to [reasons]. +Database: [Database] was selected as the storage engine due to [reasons]. + +=== System Decomposition +The [pattern] architecture pattern will be followed for structuring the system, dividing it into modules/classes responsible for [responsibilities]. + +=== Quality Goals +Performance: A quick system response will be sought, especially during question generation and gameplay. +Security: Security measures will be implemented to protect user information and ensure the integrity of generated questions. + +=== Organizational Decisions +Development Methodology: [Methodology] will be adopted for project management, facilitating collaboration and iterative delivery. \ No newline at end of file diff --git a/docs/src/07_deployment_view.adoc b/docs/src/07_deployment_view.adoc index 22b45c27..521e3efd 100644 --- a/docs/src/07_deployment_view.adoc +++ b/docs/src/07_deployment_view.adoc @@ -1,94 +1,51 @@ -ifndef::imagesdir[:imagesdir: ../images] - [[section-deployment-view]] - == Deployment View -[role="arc42help"] -**** -.Content -The deployment view describes: - - 1. 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 - -2. mapping of (software) building blocks to that infrastructure elements. - -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 a deployment view if 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 only those elements of an infrastructure that are needed to show a deployment of your building blocks. Hardware architects can go beyond that and describe an infrastructure to any level of detail they need to capture. - -.Motivation -Software does not run without hardware. -This underlying infrastructure can and will influence a system and/or some -cross-cutting concepts. Therefore, there is a need to know the infrastructure. - -.Form - -Maybe a highest level deployment diagram is already contained in section 3.2. as -technical context with your own infrastructure as ONE black box. In this section one can -zoom into this black box using additional deployment diagrams: - -* UML offers deployment diagrams to express that view. Use it, probably with nested diagrams, -when your infrastructure is more complex. -* When your (hardware) stakeholders prefer other kinds of diagrams rather than a deployment diagram, let them use any kind that is able to show nodes and channels of the infrastructure. - - -.Further Information - -See https://docs.arc42.org/section-7/[Deployment View] in the arc42 documentation. - -**** +The deployment strategy for our game, which leverages the Wikidata API to dynamically generate questions, is built around a Docker-based infrastructure. This approach allows for the encapsulation of our Java Spring Boot application within a Docker container, simplifying deployments across different environments (development, testing, and production) while ensuring consistency and isolation. === Infrastructure Level 1 -[role="arc42help"] -**** -Describe (usually in a combination of diagrams, tables, and text): - -* distribution of a system to multiple locations, environments, computers, processors, .., as well as physical connections between them -* important justifications or motivations for this deployment structure -* quality and/or performance features of this infrastructure -* mapping of software artifacts to elements of this infrastructure - -For multiple environments or alternative deployments please copy and adapt this section of arc42 for all relevant environments. -**** +Our application is containerized using Docker, enabling us to deploy the entire stack as a single `.jar` file that includes the web server. This method ensures that our application can be easily moved across environments or scaled up as needed without significant changes to the infrastructure. -_****_ +_**Overview Diagram:**_ +The infrastructure features a single Docker container that hosts the Java Spring Boot application. This container communicates with external services, such as the Wikidata API, to fetch data in real-time and generate game questions. -Motivation:: +.Motivation:: +The primary motivation behind using Docker for deployment is to streamline the development and deployment processes. By containerizing the application, we reduce discrepancies between environments, making it easier to develop, test, and deploy with confidence. -__ - -Quality and/or Performance Features:: - -__ - -Mapping of Building Blocks to Infrastructure:: -__ +.Quality and/or Performance Features:: +- **Portability:** Docker containers can run on any system that has Docker installed, reducing environment-specific bugs. +- **Scalability:** While we start with a single container, the setup can be easily scaled using Docker Compose or Docker Swarm if the need arises. +- **Efficiency:** Docker utilizes resources more efficiently than traditional VMs, allowing for faster startup times and lower overhead. +.Mapping of Building Blocks to Infrastructure:: +- **Web Server/Application (.jar file):** Packaged within a Docker container, it includes all necessary dependencies to run independently across any Docker-supported platform. +- **External APIs (e.g., Wikidata API):** Accessed over the network, these APIs provide dynamic content for the game. === Infrastructure Level 2 -[role="arc42help"] -**** -Here you can include the internal structure of (some) infrastructure elements from level 1. - -Please copy the structure from level 1 for each selected element. -**** - -==== __ +At this level, we describe the Docker container configuration that encapsulates our application. -__ +==== _Docker Container_ -==== __ +Our Docker container is built from a Java base image, which is then layered with our application’s `.jar` file. This setup encapsulates the entire runtime environment required for our application. -__ +.Diagram: Docker Container Setup:: +[plantuml,"Docker Container Setup",png] +---- +@startuml +rectangle "Docker Container" { + node "Java Spring Boot App (.jar)" as App + database "Web Server (Embedded)" as WebServer +} -... +cloud "Wikidata API" as API -==== __ +App --> API : Fetch questions +App ..> WebServer : Server application +@enduml +---- -__ +.Explanation:_ +This diagram illustrates the internal structure of our Docker container. It shows the Java Spring Boot application, including the embedded web server, packaged as a `.jar` file. The application interacts with external APIs, like the Wikidata API, to retrieve data necessary for generating game questions. The containerized approach ensures that the application can be deployed consistently across any environment that supports Docker. \ No newline at end of file diff --git a/docs/src/08_concepts.adoc b/docs/src/08_concepts.adoc index 591ccf1f..91dee5ee 100644 --- a/docs/src/08_concepts.adoc +++ b/docs/src/08_concepts.adoc @@ -3,71 +3,60 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-concepts]] == Cross-cutting Concepts +The following concepts provide a foundation for the design and implementation of the trivia game project, which utilizes the Wikidata API for dynamic question generation and employs a hexagonal architecture for its Java Spring Boot application. -[role="arc42help"] -**** -.Content -This section describes overall, principal regulations and solution ideas that are relevant in multiple parts (= cross-cutting) of your system. -Such concepts are often related to multiple building blocks. -They can include many different topics, such as +=== Domain Model -* models, especially domain models -* architecture or design patterns -* rules for using specific technology -* principal, often technical decisions of an overarching (= cross-cutting) nature -* implementation rules +The domain model for our game includes entities such as `Question`, `Category`, `Player`, and `GameSession`. These are crucial for representing the game's data and logic. The model serves as the basis for interactions within the application and between the application and the database. +.Explanation: +The `Question` entity encapsulates details of the trivia questions. `Category` classifies these questions into various topics. `Player` represents users and their interactions with the game, while `GameSession` maintains the state of play, including scores and progress. -.Motivation -Concepts form the basis for _conceptual integrity_ (consistency, homogeneity) of the architecture. -Thus, they are an important contribution to achieve inner qualities of your system. +=== Hexagonal Architecture -Some of these concepts cannot be assigned to individual building blocks, e.g. security or safety. +Our application is structured using hexagonal architecture principles, which prioritize the separation of core logic from peripheral concerns like user interface and external API interactions. +.Explanation: +This architecture facilitates the creation of a flexible and maintainable codebase. It allows for easy adaptation to changes in external services or user interface technologies without impacting the application's core logic. -.Form -The form can be varied: +=== Java Persistence API (JPA) for Data Management -* concept papers with any kind of structure -* cross-cutting model excerpts or scenarios using notations of the architecture views -* sample implementations, especially for technical concepts -* reference to typical usage of standard frameworks (e.g. using Hibernate for object/relational mapping) +We use JPA for data persistence to abstract and handle all database operations, allowing for a more streamlined and object-oriented approach to data handling. -.Structure -A potential (but not mandatory) structure for this section could be: +.Explanation: +JPA enables us to map our domain objects to the database schema with ease, providing a clear layer of abstraction that simplifies data persistence and retrieval while ensuring our application remains agnostic of the underlying database technology. -* Domain concepts -* User Experience concepts (UX) -* Safety and security concepts -* Architecture and design patterns -* "Under-the-hood" -* development concepts -* operational concepts +=== Logging with Log4j and System.out -Note: it might be difficult to assign individual concepts to one specific topic -on this list. +For monitoring runtime behavior and troubleshooting, the project utilizes Log4j and System.out for logging. While Log4j offers more sophisticated logging capabilities, System.out is used for straightforward, immediate console output. -image::08-Crosscutting-Concepts-Structure-EN.png["Possible topics for crosscutting concepts"] +.Explanation: +Log4j is configured to capture various levels of output, which can be directed to multiple destinations such as console, files, or even remote logging servers. For simplicity and immediacy during development or less complex deployment scenarios, System.out is employed for logging output directly to the console. +=== Security -.Further Information +Security is a key concern, ensuring that user data and game integrity are protected. We implement standard security practices at various levels within the application. -See https://docs.arc42.org/section-8/[Concepts] in the arc42 documentation. -**** +.Explanation: +This includes securing the web layer with Spring Security, encrypting sensitive data, and protecting against common web vulnerabilities. +=== Performance Optimization -=== __ +Performance optimization is considered in all aspects of the application, from the efficient design of the domain model to the configuration of the persistence layer. -__ +.Explanation: +We ensure that database interactions are efficient through JPA's caching and lazy loading. Queries are optimized to fetch only the necessary data, minimizing response times and resource utilization. +=== Continuous Integration and Continuous Deployment (CI/CD) +The project adheres to CI/CD practices, facilitating automated testing, building, and deployment processes which contribute to the robustness and reliability of the application. -=== __ +.Explanation: +Our CI/CD pipeline automates the process of integrating code changes, building the application, running tests, and deploying the Dockerized application, ensuring consistent and reliable delivery of updates. -__ +=== Scalability -... +Designing for scalability, the application can accommodate an increasing number of users and interactions without performance degradation. -=== __ - -__ +.Explanation: +Scalable solutions such as Docker containers allow the application to be deployed in a distributed environment, where resources can be adjusted based on demand. \ No newline at end of file diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dc5575fc..c80ed1bd 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -18,8 +18,22 @@ This should be your motto for systematic detection and evaluation of risks and t List of risks and/or technical debts, probably including suggested measures to minimize, mitigate or avoid risks or reduce technical debts. + .Further Information See https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation. **** + +[cols="1,2,3a", options="header"] +|=== +| Priority | Risk/Debt | Description + +| High | Migration to Java | migration from the current project language, JavaScript (JS), to Java +| Medium | IDE Configuration | Version compatibility, extensions and other preferences to work perfectly without conflicts +| Medium | Database | discuss which database is best for the project +| Low | Docker | Know how docker works, what it is for, how it is used and what its alternatives could be. +| Low | Microservices | Research about microservices and what they can contribute to the project + + +|=== diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 192b2353..27a32160 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -34,9 +34,18 @@ See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation. |=== |Term |Definition -| -| +|wikiData +|A collaborative platform that provides structured data for Wikimedia projects, including Wikipedia. -| -| +|IDE (Integrated Development Environment) +|A software application that provides comprehensive facilities to programmers for software development. + +|Docker +|An open-source platform designed to automate the deployment of applications inside lightweight, portable containers. + +|Microservices +|An architectural style that structures an application as a collection of small, independent services. + +|API (Application Programming Interface) +|A set of protocols and tools for building software applications, allowing them to communicate with each other. |===