From d45ed0cd86bfc4ef3a72079b32878bb2f2b1cbb6 Mon Sep 17 00:00:00 2001 From: Pelayori <31128562+Pelayori@users.noreply.github.com> Date: Mon, 11 Mar 2024 20:22:55 +0100 Subject: [PATCH] Update some parts of the documentation. Finished section 5 --- docs/src/01_introduction_and_goals.adoc | 88 +------ docs/src/02_architecture_constraints.adoc | 25 +- docs/src/03_system_scope_and_context.adoc | 90 ++----- docs/src/04_solution_strategy.adoc | 44 +--- docs/src/05_building_block_view.adoc | 290 ++++++---------------- docs/src/06_runtime_view.adoc | 35 --- docs/src/09_architecture_decisions.adoc | 31 --- docs/src/10_quality_requirements.adoc | 68 ----- docs/src/11_technical_risks.adoc | 23 -- docs/src/12_glossary.adoc | 28 --- 10 files changed, 113 insertions(+), 609 deletions(-) diff --git a/docs/src/01_introduction_and_goals.adoc b/docs/src/01_introduction_and_goals.adoc index a8be2ead..99812040 100644 --- a/docs/src/01_introduction_and_goals.adoc +++ b/docs/src/01_introduction_and_goals.adoc @@ -2,49 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-introduction-and-goals]] == Introduction and Goals -[role="arc42help"] -**** -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 -**** -WIQ is a game developed by HappySw for: - -* Challenging "Saber y ganar" fans -* Learning to perform teamwork -* Passing the "Software Architecture" subject -* Improving as software engineers - -=== Requirements Overview -[role="arc42help"] -**** -.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 https://docs.arc42.org/section-1/[Introducdction and Goals] in the arc42 documentation. - -**** - This web application, inspired by the famous Spanish TV show "Saber y ganar," consists of a mini-game of questions and answers. In this game, the player is asked a question and presented with four possible answers, of which only one is correct. @@ -60,57 +17,18 @@ The application automatically generates questions with the help of Wikidata (the to constantly update the questions instead of storing them in a database. === Quality Goals - -[role="arc42help"] -**** -.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): - -image::01_2_iso-25010-topics-EN.drawio.png["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 -**** - [options="header",cols="1,2,2"] |=== |Nº|Atributo|Motivacion | 1 | Efficiency | Access, creation of questions, and navigation between them should be fast to ensure user satisfaction. | 2 | Usability | The application should be appealing to all fans of the original program while also offering a wide variety of questions. -| 3 | Manteinence | The application should ensure easy expansion and modification to provide users with new features. +| 3 | Manteinance | The application should ensure easy expansion and modification to provide users with new features. +| 4 | Availability | Our goal is to achieve at least 95% availability, ensuring that the system is always available for users to play. +| 5 | Responsiveness | The system must be responsive, providing a good user experience for those in desktop and mobile environments. |=== === Stakeholders -[role="arc42help"] -**** -.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. -**** - [options="header",cols="1,2"] |=== |Role/Name|Expectations diff --git a/docs/src/02_architecture_constraints.adoc b/docs/src/02_architecture_constraints.adoc index 5b97a2d6..d63210f6 100644 --- a/docs/src/02_architecture_constraints.adoc +++ b/docs/src/02_architecture_constraints.adoc @@ -3,29 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-architecture-constraints]] == Architecture Constraints - -[role="arc42help"] -**** -.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 https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 documentation. - -**** - - *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. @@ -39,7 +16,7 @@ See https://docs.arc42.org/section-2/[Architecture Constraints] in the arc42 doc The questions must have a limited time to be responded. - *Questions must have 4 posible answers* - Each question will have one correct answer and several incorrect or distractor answers. Both the correct and incorrect answers will be generated automatically. + Each question will have one correct answer and several incorrect answers. Both the correct and incorrect answers will be generated automatically. - *System API:* System will allow accessing user information and the information of the generated questions through an API. diff --git a/docs/src/03_system_scope_and_context.adoc b/docs/src/03_system_scope_and_context.adoc index c24d4270..4a0c9352 100644 --- a/docs/src/03_system_scope_and_context.adoc +++ b/docs/src/03_system_scope_and_context.adoc @@ -3,91 +3,37 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-system-scope-and-context]] == System Scope and Context - -[role="arc42help"] -**** -.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 https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation. - -**** - - === Business Context - - -[role="arc42help"] -**** -.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. - -**** - [plantuml,"Deployment diagram",png] ---- - actor user - component System[ - <> - QuestionGame - ] - component WikiData - database Database +@startuml +actor Player as user +actor "External Developers" as developers +component System [ + <> + QuestionGame +] +component WikiData as wikidata +database Database + +user -down-> System : Uses +System -right-> Database : Stores/Fetches\nData +System -left-> wikidata : Retrieves\nInformation +developers -down-> System : Accesses via\nREST API +System -----> developers : Provides\nPlayer &\n Question Data +@enduml - user --> System - System --> Database - System --> WikiData ---- - -* **User:** Represents users who interact with the application to play games or view their history. +* **Player:** 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. +* **External Developers:** Represents developers who access the system's REST API to retrieve player and question data. === Technical Context -[role="arc42help"] -**** -.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. - -**** - [plantuml,"Technical Context Diagram",png] ---- - actor user person developer database Database diff --git a/docs/src/04_solution_strategy.adoc b/docs/src/04_solution_strategy.adoc index bb21e2f6..8da69862 100644 --- a/docs/src/04_solution_strategy.adoc +++ b/docs/src/04_solution_strategy.adoc @@ -3,47 +3,25 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-solution-strategy]] == Solution Strategy - -[role="arc42help"] -**** -.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 https://docs.arc42.org/section-4/[Solution Strategy] in the arc42 documentation. - -**** - -There are some placeholders for the decisions yet to be taken. - === Technological Decisions * Programming Language: Java will be used for system development because all team members are familiar with it, and we believe we can perform better using this language. * Frontend Framework: SpringBoot will be adopted for frontend development because it allows us to deploy a web application using Java and provides numerous functionalities that greatly facilitate the implementation of project requirements, such as user authentication. -* Database: HSQLDB for local tests and MySQL for production were selected as the storages engines due to Java being the chosen language. +* Database: A relational database will be used. HSQLDB for local tests and MySQL for production were selected as the storages engines due to the modeled entities having a strong, fixed structure and the multiple relationships between them. Besides that, the team has experience with these databases and will allow an easier flow of development. === System Decomposition -The Model-View-Controler architecture pattern will be followed for structuring the system, dividing it into modules/classes responsible for the managment of the players, questions, answers and game, and the viiews of the frontend. +The Model-View-Controler architecture pattern will be followed for structuring the system, dividing it into modules/classes responsible for the managment of the players, questions, answers and game, and the views of the frontend. === 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. +* Availability: +* Responsiveness: +* Usability: The system must be easy to use, with a simple and intuitive interface. === Organizational Decisions -Development Methodology: GitFlow will be adopted for project management, facilitating collaboration and iterative delivery. \ No newline at end of file +Development Methodology: GitFlow will be adopted for project management, facilitating collaboration and iterative delivery. + +* The default branch: master. This branch will only be used to create new releases and will contain the most stable version of the system. +* The development branch: develop. This branch will be used to integrate the features developed by the team and will be the basis for creating new releases. This will have the largest commit amount, and will also have a stable version that could be deployed at any time. +* Feature branches: These branches will be used to develop new features, and will be created from the develop branch. After the feature is developed, it will be merged into the develop branch and branch can be deleted, although we will not usually delete branches. +* Fix branches: These branches will be used to fix bugs, and will be created from the develop branch. After the bug is fixed, it will be merged into the develop branch and branch can be deleted, although we will not usually delete branches. \ No newline at end of file diff --git a/docs/src/05_building_block_view.adoc b/docs/src/05_building_block_view.adoc index 1ed04f11..2dab66db 100644 --- a/docs/src/05_building_block_view.adoc +++ b/docs/src/05_building_block_view.adoc @@ -1,251 +1,121 @@ -ifndef::imagesdir[:imagesdir: ../images] += Building Block View -[[section-building-block-view]] +The Building Block View elaborates on the static structure of the system. It decomposes the system into building blocks like modules, components, subsystems, and others, detailing their responsibilities and relationships. +== 5.1 Whitebox Overall System -== Building Block View +This section provides an overview of the main components of the system and their interactions. The core of the system is the WIQ (QuestionGame) component, which interfaces with Users, Wikidata for question generation, a Database for persistence, and offers a REST API for External Developers. -[role="arc42help"] -**** -.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. - -image::05_building_blocks-EN.png["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 https://docs.arc42.org/section-5/[Building Block View] in the arc42 documentation. - -**** - -=== Whitebox Overall System - -[role="arc42help"] -**** -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. - -**** - -[plantuml,"Whitebox Overall System",png] +[plantuml,"Whitebox-overall",png] ---- -actor User as User -rectangle "WIQ" { - User --> WIQ : Interacts with +@startuml +!theme plain + +actor User +actor "External Developers" as Dev +component "[WIQ QuestionGame]" as WIQ { + component "[Game Logic]" as Logic + component "[User Account\nManagement]" as UserMgmt + component "[Question\nManagement]" as QuestMgmt + component "[API\nManagement]" as APIMgmt } +database "Database" as DB +[WikiData] as WikiData -rectangle "Wikidata" { - WIQ --> Wikidata : Requests data to generate questions -} +User --> WIQ : Interacts +WIQ --> WikiData : Fetches data +WIQ --> DB : Reads/Writes Data +Dev --> APIMgmt : Uses APIs -rectangle "DataBase" { - WIQ --> DataBase : Saves the users and games -} +@enduml ---- +=== Motivation -Motivation:: +The decomposition provides a clear, high-level overview of how the WIQ system interacts with users, external services (Wikidata), stores data (Database), and interfaces with external developers through the REST API. This modularity supports scalability and maintainability. -The purpose of this whitebox is to provide a clear, simple overview without delving into details of how the WIQ system interacts -with the external Wikidata service to obtain the necessary data for question generation. By presenting this interaction clearly, -stakeholders can easily understand how the WIQ system integrates with external data sources and how that information is used to -fulfill system requirements related to the automatic generation of questions. +=== Contained Building Blocks - -Contained Building Blocks:: -[cols="1,2" options="header"] +[options="header"] |=== | Name | Description | User -| It represents the user interacting with the WIQ application. +| Represents the end users of the WIQ application, interacting with the system to play games and view their history. -| WIQ -| It represents the main WIQ application. +| WIQ (QuestionGame) +| The central component that manages gameplay logic, user interactions, and integrates external data for question generation. | Wikidata -| External service used by WIQ to obtain data and generate questions. - -| DataBase -| The DataBase that save the accounts of the players and the games that they played. -|=== - - -In progress...:: -We have yet to decide the precise composition of our system so we can´t fill the rest of this section yet. - - -Important Interfaces:: -__ +| An external service utilized by the WIQ system to retrieve data for dynamically generating quiz questions. +| Database +| Maintains persistent storage for user data, game history, and generated questions, ensuring data integrity and availability. -[role="arc42help"] -**** -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: - -[cols="1,2" options="header"] -|=== -| **Name** | **Responsibility** -| __ | __ -| __ | __ +| External Developers +| Developers or systems that interact with the WIQ system via the REST API to access or modify player and question data. |=== +== 5.2 Level 2 +For Level 2 of the Building Block View, the WIQ (QuestionGame) system is further decomposed into four primary components that define its operational structure. Each component is designed to fulfill specific roles within the architecture, ensuring the system's functionality and responsiveness to user interactions. -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. -**** - - -==== - -[role="arc42help"] -**** -Here you describe -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 - -**** - -__ +* *Game Logic:* This component acts as the core of the QuestionGame, orchestrating the flow of games, managing question selection, enforcing game rules, and tracking scores. It ensures that gameplay proceeds smoothly and according to the predefined logic, offering a seamless experience for the user. -__ +* *User Account Management:* Responsible for handling user accounts, this component manages registration, authentication, and profile management. It safeguards user data while providing a personalized experience through game history tracking and preference settings. -_<(Optional) Quality/Performance Characteristics>_ +* *Question Management:* This component interacts directly with the Wikidata service to fetch data for question generation. It processes and curates content to produce relevant, challenging questions for the game, thereby ensuring a varied and educational experience. -_<(Optional) Directory/File Location>_ +* *API Management:* Serving as the gateway for external developers, this component exposes a set of RESTful APIs that allow access to player information and question data. It handles request processing, authentication, and data delivery, facilitating third-party integrations and extensions of the WIQ platform. -_<(Optional) Fulfilled Requirements>_ -_<(optional) Open Issues/Problems/Risks>_ - - - - -==== - -__ - -==== - -__ - - -==== - -... - -==== - - - -=== Level 2 - -[role="arc42help"] -**** -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 -**** - -==== White Box __ - -[role="arc42help"] -**** -...describes the internal structure of _building block 1_. -**** - -__ - -==== White Box __ - - -__ - -... - -==== White Box __ - - -__ - - - -=== Level 3 - -[role="arc42help"] -**** -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. -**** - - -==== White Box <_building block x.1_> +[plantuml,"level2",png] +---- +@startuml +!theme plain + +package "WIQ QuestionGame" { + component "[Game Logic]" as Logic + component "[User Account\nManagement]" as UserMgmt + component "[Question\nManagement]" as QuestMgmt + component "[API\nManagement]" as APIMgmt + + UserMgmt -[hidden]-> Logic : <> + QuestMgmt -[hidden]-> Logic : <> + APIMgmt -[hidden]-> UserMgmt : <> + APIMgmt -[hidden]-> QuestMgmt : <> + + Logic ..> UserMgmt : Uses + Logic ..> QuestMgmt : Uses + UserMgmt ..> APIMgmt : Interfaces + QuestMgmt ..> APIMgmt : Interfaces +} -[role="arc42help"] -**** -Specifies the internal structure of _building block x.1_. -**** +@enduml +---- +== 5.3 Level 3 -__ +In Level 3, we take a closer look at the API Management component, breaking it down into two essential services: the Player Information API and the Question Information API. These services are fundamental to the system's ability to interact with external applications, providing necessary functionalities with a focus on usability and security. +* *Player Information API:* This API serves as the gateway for external applications to access and manage player data. It allows for operations such as retrieving player profiles, updating personal information, and viewing game history. The design prioritizes data security, ensuring safe and secure access to sensitive information. The interface is straightforward, designed for ease of use while maintaining comprehensive functionality. -==== White Box <_building block x.2_> +* *Question Information API:* Dedicated to the dynamic world of quiz questions, this API facilitates the retrieval of questions and submission of answers. It stands as a bridge between the system's vast question repository and external applications, enabling a seamless flow of information. The API adheres to clear and logical request and response structures, ensuring efficient and effective communication. Security measures are in place to protect the integrity of the question data and the fairness of the game. -__ +This level of documentation provides a structured and clear view of the system's architecture, particularly focusing on its integration points. By balancing formal language with accessibility, we aim to communicate effectively with a broad audience of stakeholders, ensuring understanding and transparency in the system's design. +[plantuml,"level3",png] +---- +@startuml +!theme plain +package "API Management" { + interface "Player Information API" as PlayerAPI + interface "Question Information API" as QuestAPI -==== White Box <_building block y.1_> + [External Developers] -right-> PlayerAPI : Uses + [External Developers] -left-> QuestAPI : Uses +} -__ +@enduml +---- \ No newline at end of file diff --git a/docs/src/06_runtime_view.adoc b/docs/src/06_runtime_view.adoc index e23b92f3..88834fa5 100644 --- a/docs/src/06_runtime_view.adoc +++ b/docs/src/06_runtime_view.adoc @@ -2,41 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-runtime-view]] == Runtime View - - -[role="arc42help"] -**** -.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 https://docs.arc42.org/section-6/[Runtime View] in the arc42 documentation. - -**** - === User Authentication [plantuml,"Sequence diagram 1",png] ---- diff --git a/docs/src/09_architecture_decisions.adoc b/docs/src/09_architecture_decisions.adoc index ee395a22..8d42e6df 100644 --- a/docs/src/09_architecture_decisions.adoc +++ b/docs/src/09_architecture_decisions.adoc @@ -3,37 +3,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-design-decisions]] == Architecture Decisions - -[role="arc42help"] -**** -.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 (https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[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 https://docs.arc42.org/section-9/[Architecture Decisions] in the arc42 documentation. -There you will find links and examples about ADR. - -**** - The purpose of this section is to create an ordered list of architectural decisions that we will make as we develop the project. This list will be ordered according to the importance of the decision. * https://github.com/Arquisoft/wiq_es04b/wiki/Record-of-architectural-decisions#protection-of-the-master-branch[ADR 01] - Protection of the master branch diff --git a/docs/src/10_quality_requirements.adoc b/docs/src/10_quality_requirements.adoc index 837fb423..175b66ff 100644 --- a/docs/src/10_quality_requirements.adoc +++ b/docs/src/10_quality_requirements.adoc @@ -2,50 +2,7 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-quality-scenarios]] == Quality Requirements - - -[role="arc42help"] -**** - -.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 https://docs.arc42.org/section-10/[Quality Requirements] in the arc42 documentation. - -**** - === Quality Tree - -[role="arc42help"] -**** -.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. - - -**** - _Note: Items (1), (2), (3) in the table below repeat the higher-level quality requirements of Chapter 1.2._ [cols="4", options="header"] @@ -94,31 +51,6 @@ _Note: Items (1), (2), (3) in the table below repeat the higher-level quality re |=== === Quality Scenarios - -[role="arc42help"] -**** -.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. -**** - [cols="2", options="header"] |=== |Identification |Scenario diff --git a/docs/src/11_technical_risks.adoc b/docs/src/11_technical_risks.adoc index dda9511e..e1cfdd1b 100644 --- a/docs/src/11_technical_risks.adoc +++ b/docs/src/11_technical_risks.adoc @@ -2,29 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-technical-risks]] == Risks and Technical Debts - - -[role="arc42help"] -**** -.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 https://docs.arc42.org/section-11/[Risks and Technical Debt] in the arc42 documentation. - -**** - [cols="1,2,3a", options="header"] |=== | Priority | Risk | Description diff --git a/docs/src/12_glossary.adoc b/docs/src/12_glossary.adoc index 4a27d5aa..b8a06dc2 100644 --- a/docs/src/12_glossary.adoc +++ b/docs/src/12_glossary.adoc @@ -2,34 +2,6 @@ ifndef::imagesdir[:imagesdir: ../images] [[section-glossary]] == Glossary - -[role="arc42help"] -**** -.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 and . - -Potentially more columns in case you need translations. - - -.Further Information - -See https://docs.arc42.org/section-12/[Glossary] in the arc42 documentation. - -**** - [cols="1,2" options="header"] |=== | Term | Definition