Skip to content

Commit

Permalink
Finish docs 7-8 first version (#28)
Browse files Browse the repository at this point in the history 
* create branch

* typo in uml

* Finish 7 and 8
  • Loading branch information
@Pelayori
Pelayori authored Feb 12, 2024
1 parent 3e4e416 commit fba1866
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 118 deletions.
105 changes: 31 additions & 74 deletions docs/src/07_deployment_view.adoc
View file
Original file line number Diff line number Diff line change
@@ -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>**_
_**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.

_<explanation in text form>_

Quality and/or Performance Features::

_<explanation in text form>_

Mapping of Building Blocks to Infrastructure::
_<description of the mapping>_
.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.
****

==== _<Infrastructure Element 1>_
At this level, we describe the Docker container configuration that encapsulates our application.

_<diagram + explanation>_
==== _Docker Container_

==== _<Infrastructure Element 2>_
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 + explanation>_
.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
==== _<Infrastructure Element n>_
App --> API : Fetch questions
App ..> WebServer : Server application
@enduml
----

_<diagram + explanation>_
.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.
77 changes: 33 additions & 44 deletions docs/src/08_concepts.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

=== _<Concept 1>_
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>_
.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.

=== _<Concept 2>_
.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.

_<explanation>_
=== Scalability

...
Designing for scalability, the application can accommodate an increasing number of users and interactions without performance degradation.

=== _<Concept n>_

_<explanation>_
.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.

0 comments on commit fba1866

Please sign in to comment.