docs: Update project documentation with architecture details

docs/projektdokumentation.tex

@@ -19,6 +19,9 @@
 \usepackage{enumitem}
 \usepackage{tikz}
 \usetikzlibrary{arrows.meta, positioning}
+\usepackage{pdflscape}
+\usepackage{afterpage}
+\usepackage{needspace}
 
 % Seitenränder
 \geometry{
@@ -266,33 +269,203 @@ Guards → Components → Services → HTTP Interceptors → Backend APIs
 Angular Router → Lazy Loading → Feature Modules
 \end{verbatim}
 
-\subsection{Systemarchitektur}
-Die Casino Gaming Platform basiert auf einer modernen Microservice-Architektur mit klarer Trennung zwischen Frontend und Backend.
+\subsection{Systemarchitektur nach C4-Modell}
+Die Casino Gaming Platform basiert auf einer modernen, schichtbasierten Architektur mit klarer Trennung zwischen Frontend und Backend. Die Darstellung erfolgt mittels des C4-Architekturmodells (Context, Container, Component, Code), welches eine hierarchische Sichtweise auf die Softwarearchitektur ermöglicht.
 
-\subsubsection{Gesamtarchitektur}
+\clearpage
+\needspace{8\baselineskip}
+\subsubsection{Ebene 1: Systemkontext-Diagramm}
+Das Systemkontext-Diagramm stellt die Casino Gaming Platform in ihrem geschäftlichen Umfeld dar und zeigt die Beziehungen zu externen Akteuren und Systemen. Es verdeutlicht, wer das System nutzt und mit welchen externen Systemen es interagiert.
+
+\begin{landscape}
 \begin{tikzpicture}[
-  box/.style={rectangle, draw, minimum width=3cm, minimum height=1.5cm, align=center},
-  ->, >=Stealth, node distance=2cm and 1.5cm
+  person/.style={rectangle, draw=blue!80, fill=blue!15, minimum width=3cm, minimum height=1.8cm, align=center, rounded corners=3pt, thick},
+  system/.style={rectangle, draw=blue!80, fill=blue!60, minimum width=5cm, minimum height=2.5cm, align=center, text=white, rounded corners=5pt, thick},
+  external/.style={rectangle, draw=gray!80, fill=gray!20, minimum width=3.5cm, minimum height=1.8cm, align=center, rounded corners=3pt, thick},
+  ->, >=Stealth, node distance=4cm, thick
 ]
 
-% Top row
-\node[box] (angular) {Angular\\Frontend};
-\node[box, right=of angular] (spring) {Spring Boot\\Backend};
-\node[box, right=of spring] (postgres) {PostgreSQL\\Database};
+% Akteure
+\node[person] (player) at (-8, 3) {\textbf{Casino-Spieler}\\Nutzt die Plattform\\für Online-Gaming};
+\node[person] (admin) at (-8, -3) {\textbf{System-Administrator}\\Verwaltet Plattform\\und Benutzer};
 
-% Bottom row
-\node[box, below=of angular] (keycloak) {Keycloak\\Auth Server};
-\node[box, below=of spring] (stripe) {Stripe API\\Payment};
+% Hauptsystem
+\node[system] (casino) at (0, 0) {\textbf{Casino Gaming Platform}\\Bietet Online-Casino-Spiele\\mit virtueller Währung und\\Zahlungsabwicklung};
 
-% Arrows top row
-\draw (angular) -- (spring);
-\draw (spring) -- (postgres);
+% Externe Systeme
+\node[external] (stripe) at (8, 3) {\textbf{Stripe API}\\Zahlungsabwicklung};
+\node[external] (email) at (8, 0) {\textbf{E-Mail-Service}\\Verifizierung \&\\Benachrichtigungen};
+\node[external] (oauth) at (8, -3) {\textbf{OAuth-Provider}\\GitHub, Google};
 
-% Arrows to bottom row
-\draw (angular.south) -- (keycloak.north);
-\draw (spring.south) -- (stripe.north);
+% Beziehungen
+\draw (player) -- (casino) node[midway, above] {Spielt Spiele, tätigt Einzahlungen};
+\draw (admin) -- (casino) node[midway, below] {Administriert System};
+\draw (casino) -- (stripe) node[midway, above] {Verarbeitet Zahlungen};
+\draw (casino) -- (email) node[midway, above] {Sendet E-Mails};
+\draw (casino) -- (oauth) node[midway, below] {Authentifiziert Benutzer};
 
 \end{tikzpicture}
+\end{landscape}
+
+\clearpage
+\needspace{8\baselineskip}
+\subsubsection{Ebene 2: Container-Diagramm}
+Das Container-Diagramm zeigt die High-Level-Architektur der Software und stellt die verschiedenen ausführbaren Einheiten (Container) sowie deren Kommunikation dar. Jeder Container repräsentiert eine separate deploybare/ausführbare Einheit wie eine Webanwendung, Datenbank oder Microservice.
+
+\begin{landscape}
+\begin{tikzpicture}[
+  webapp/.style={rectangle, draw=blue!80, fill=blue!25, minimum width=4cm, minimum height=2.5cm, align=center, rounded corners=4pt, thick},
+  api/.style={rectangle, draw=green!80, fill=green!25, minimum width=4cm, minimum height=2.5cm, align=center, rounded corners=4pt, thick},
+  database/.style={rectangle, draw=red!80, fill=red!25, minimum width=3.5cm, minimum height=2.2cm, align=center, rounded corners=4pt, thick},
+  external/.style={rectangle, draw=gray!80, fill=gray!20, minimum width=3.2cm, minimum height=1.8cm, align=center, rounded corners=3pt, thick},
+  ->, >=Stealth, node distance=4cm, thick
+]
+
+% Akteur
+\node[webapp] (person) at (-10, 5) {\textbf{Casino-Spieler}\\Person\\Nutzt Webbrowser\\oder Mobile App};
+
+% Frontend-Container
+\node[webapp] (frontend) at (-5, 1) {\textbf{Webanwendung}\\Angular 20, TypeScript\\Liefert statische Inhalte\\und Casino-Spiele-UI};
+
+% Backend-Container
+\node[api] (backend) at (2, 1) {\textbf{API-Anwendung}\\Spring Boot, Java\\Stellt Spiellogik,\\Benutzerverwaltung und\\Geschäftsregeln bereit};
+
+% Datenbank
+\node[database] (database) at (2, -4) {\textbf{Datenbank}\\PostgreSQL\\Speichert Benutzerkonten,\\Spielhistorie und\\Transaktionen};
+
+% Externe Systeme
+\node[external] (stripe) at (9, 4) {\textbf{Stripe API}\\Zahlungssystem};
+\node[external] (email) at (9, 1) {\textbf{Mailpit}\\E-Mail-Service};
+\node[external] (oauth) at (9, -2) {\textbf{OAuth-Provider}\\Authentifizierungsdienste};
+
+% Beziehungen
+\draw (person) -- (frontend) node[midway, above] {HTTPS};
+\draw (frontend) -- (backend) node[midway, above] {REST API\\JSON/HTTPS};
+\draw (backend) -- (database) node[midway, right] {JDBC\\SQL};
+\draw (backend) -- (stripe) node[midway, above] {HTTPS\\Webhooks};
+\draw (backend) -- (email) node[midway, right] {SMTP};
+\draw (backend) -- (oauth) node[midway, below] {OAuth2\\HTTPS};
+
+\end{tikzpicture}
+\end{landscape}
+
+\clearpage
+\needspace{8\baselineskip}
+\subsubsection{Ebene 3: Komponenten-Diagramm - Backend API}
+Das Komponenten-Diagramm zeigt die interne Struktur des Backend API-Containers und stellt die wichtigsten Softwarekomponenten sowie deren Abhängigkeiten dar. Es verdeutlicht die Architektur nach dem MVC-Pattern mit Controller-, Service- und Repository-Schichten.
+
+\begin{landscape}
+\begin{tikzpicture}[
+  component/.style={rectangle, draw=yellow!80, fill=yellow!15, minimum width=3.2cm, minimum height=1.8cm, align=center, rounded corners=3pt, thick},
+  controller/.style={rectangle, draw=blue!80, fill=blue!20, minimum width=3.2cm, minimum height=1.8cm, align=center, rounded corners=3pt, thick},
+  service/.style={rectangle, draw=green!80, fill=green!20, minimum width=3.2cm, minimum height=1.6cm, align=center, rounded corners=3pt, thick},
+  repository/.style={rectangle, draw=orange!80, fill=orange!20, minimum width=3.2cm, minimum height=1.4cm, align=center, rounded corners=3pt, thick},
+  ->, >=Stealth, node distance=3cm, thick
+]
+
+% Controller (API-Schicht)
+\node[controller] (auth-ctrl) at (-8, 5) {\textbf{Auth Controller}\\Anmeldung, Registrierung,\\OAuth};
+\node[controller] (game-ctrl) at (-3, 5) {\textbf{Spiele-Controller}\\Blackjack, Slots,\\Würfel, etc.};
+\node[controller] (deposit-ctrl) at (2, 5) {\textbf{Einzahlungs-Controller}\\Zahlungs-\\abwicklung};
+\node[controller] (user-ctrl) at (7, 5) {\textbf{Benutzer-Controller}\\Profil-\\verwaltung};
+
+% Services (Geschäftslogik-Schicht)
+\node[service] (auth-svc) at (-8, 2.5) {\textbf{Auth Service}\\Authentifizierungs-\\logik};
+\node[service] (game-svc) at (-3, 2.5) {\textbf{Spiele-Services}\\Spiellogik und\\Regeln};
+\node[service] (balance-svc) at (2, 2.5) {\textbf{Guthaben-Service}\\Transaktions-\\verwaltung};
+\node[service] (user-svc) at (7, 2.5) {\textbf{Benutzer-Service}\\Benutzer-\\verwaltung};
+
+% Repositories (Datenschicht)
+\node[repository] (user-repo) at (-5.5, 0) {\textbf{Benutzer-Repository}\\JPA/Hibernate};
+\node[repository] (game-repo) at (-0.5, 0) {\textbf{Spiele-Repository}\\JPA/Hibernate};
+\node[repository] (transaction-repo) at (4.5, 0) {\textbf{Transaktions-Repo}\\JPA/Hibernate};
+
+% Sicherheitskomponenten
+\node[component] (security) at (-11, 2.5) {\textbf{Security Config}\\JWT-Filter,\\CORS, OAuth2};
+
+% Relationships
+\draw (auth-ctrl) -- (auth-svc);
+\draw (game-ctrl) -- (game-svc);
+\draw (deposit-ctrl) -- (balance-svc);
+\draw (user-ctrl) -- (user-svc);
+
+\draw (auth-svc) -- (user-repo);
+\draw (game-svc) -- (game-repo);
+\draw (balance-svc) -- (transaction-repo);
+\draw (user-svc) -- (user-repo);
+
+\draw (security) -- (auth-svc);
+
+\end{tikzpicture}
+\end{landscape}
+
+\clearpage
+\needspace{8\baselineskip}
+\subsubsection{Ebene 4: Code-Diagramm - Blackjack Service Implementierung}
+Das Code-Diagramm zeigt exemplarisch die Implementierungsdetails des Blackjack Game Service auf Klassenebene. Es stellt die wichtigsten Klassen, Interfaces und deren Beziehungen dar, die für die Blackjack-Spiellogik verantwortlich sind.
+
+\begin{landscape}
+\begin{tikzpicture}[
+  class/.style={rectangle, draw=cyan!80, fill=cyan!15, minimum width=3.5cm, minimum height=3cm, align=center, rounded corners=4pt, thick},
+  interface/.style={rectangle, draw=yellow!80, fill=yellow!15, minimum width=3cm, minimum height=2cm, align=center, rounded corners=4pt, thick},
+  ->, >=Stealth, node distance=4.5cm, thick
+]
+
+% Interface - kompaktere Anordnung
+\node[interface] (game-interface) at (0, 4) {\textbf{<<Interface>>}\\GameService\\+spielStarten()\\+zugVerarbeiten()\\+ergebnisBerechnen()};
+
+% Haupt-Service-Klasse
+\node[class] (blackjack-service) at (0, 1) {\textbf{BlackjackService}\\implementiert GameService\\- kartendeck: Deck\\- spielRepository: Repository\\+ neuesSpielStarten(einsatz)\\+ ziehen(spielId)\\+ halten(spielId)\\+ verdoppeln(spielId)};
+
+% Unterstützende Klassen - kompakter angeordnet
+\node[class] (card-deck) at (-5, 1) {\textbf{Kartendeck}\\- karten: List<Karte>\\+ mischen()\\+ karteGeben()\\+ zurücksetzen()};
+
+\node[class] (game-entity) at (5, 1) {\textbf{BlackjackSpielEntity}\\- id: Long\\- spielerKarten: List<Karte>\\- dealerKarten: List<Karte>\\- einsatzBetrag: BigDecimal\\- spielZustand: SpielZustand};
+
+\node[class] (balance-service) at (0, -2) {\textbf{GuthabenService}\\+ guthabenAktualisieren()\\+ ausreichendGuthaben()\\+ transaktionErstellen()};
+
+% Beziehungen
+\draw (blackjack-service) -- (game-interface) node[midway, right] {implementiert};
+\draw (blackjack-service) -- (card-deck) node[midway, above] {verwendet};
+\draw (blackjack-service) -- (game-entity) node[midway, above] {verwaltet};
+\draw (blackjack-service) -- (balance-service) node[midway, right] {abhängig von};
+
+\end{tikzpicture}
+\end{landscape}
+
+\clearpage
+\needspace{8\baselineskip}
+\subsubsection{Deployment-Diagramm}
+Das Deployment-Diagramm zeigt die Verteilung der Software-Container auf die physische/virtuelle Infrastruktur und stellt die Laufzeitumgebung der Anwendung dar. Es verdeutlicht, wie die verschiedenen Komponenten in der Produktionsumgebung deployed werden.
+
+\begin{landscape}
+\begin{tikzpicture}[
+  node/.style={rectangle, draw=gray!80, fill=gray!15, minimum width=5cm, minimum height=4cm, align=center, rounded corners=5pt, thick},
+  container/.style={rectangle, draw=blue!80, fill=blue!20, minimum width=3cm, minimum height=2cm, align=center, rounded corners=4pt, thick},
+  ->, >=Stealth, node distance=6cm, thick
+]
+
+% Infrastruktur-Knoten
+\node[node] (docker-host) at (0, 0) {\textbf{Docker-Host}\\Ubuntu Linux\\Docker Engine 24.x};
+
+% Container innerhalb des Docker-Hosts - kompaktere Anordnung
+\node[container] (nginx) at (-4, 2.5) {\textbf{nginx}\\Webserver\\Port 80/443};
+\node[container] (angular) at (-1.5, 2.5) {\textbf{Frontend}\\Angular-App\\Statische Dateien};
+\node[container] (spring) at (1.5, 2.5) {\textbf{Backend}\\Spring Boot\\Port 8080};
+\node[container] (postgres) at (4, 2.5) {\textbf{Datenbank}\\PostgreSQL\\Port 5432};
+\node[container] (mailpit) at (0, -2.5) {\textbf{Mailpit}\\E-Mail-Service\\Port 1025/8025};
+
+% Externe Dienste - näher platziert
+\node[node] (cloud) at (7, 0) {\textbf{Cloud-Dienste}\\Stripe API\\OAuth-Provider};
+
+% Beziehungen
+\draw (nginx) -- (angular);
+\draw (spring) -- (postgres);
+\draw (spring) -- (mailpit);
+\draw (spring) -- (cloud);
+
+\end{tikzpicture}
+\end{landscape}
 
 \subsubsection{Backend-Paketstruktur}
 Das Backend folgt dem Domain-Driven Design (DDD) Ansatz:
@@ -335,8 +508,73 @@ Das Backend folgt dem Domain-Driven Design (DDD) Ansatz:
 .3 UserService.java.
 }
 
-\subsubsection{Frontend-Modulstruktur}
-Das Frontend ist modular aufgebaut mit Feature-Modulen:
+\clearpage
+\needspace{8\baselineskip}
+\subsubsection{Ebene 3: Komponenten-Diagramm - Frontend-Anwendung}
+Das Komponenten-Diagramm zeigt die interne Struktur der Angular Frontend-Anwendung und stellt die modulare Architektur mit Feature-Modulen, Services und Guards dar. Es verdeutlicht die Anwendung des Angular-Framework-Patterns.
+
+\begin{landscape}
+\begin{tikzpicture}[
+  module/.style={rectangle, draw=purple!80, fill=purple!20, minimum width=3.5cm, minimum height=2.2cm, align=center, rounded corners=4pt, thick},
+  component/.style={rectangle, draw=blue!80, fill=blue!20, minimum width=3cm, minimum height=1.6cm, align=center, rounded corners=3pt, thick},
+  service/.style={rectangle, draw=green!80, fill=green!20, minimum width=3cm, minimum height=1.6cm, align=center, rounded corners=3pt, thick},
+  guard/.style={rectangle, draw=orange!80, fill=orange!20, minimum width=3cm, minimum height=1.6cm, align=center, rounded corners=3pt, thick},
+  ->, >=Stealth, node distance=3.5cm, thick
+]
+
+% Kern-Module - kompaktere Anordnung
+\node[module] (app) at (0, 5) {\textbf{App-Modul}\\Haupt-Modul\\mit Routing};
+\node[module] (shared) at (-6, 3) {\textbf{Shared-Modul}\\Gemeinsame Komponenten\\Navbar, Footer};
+
+% Feature-Module - dichter angeordnet
+\node[module] (auth) at (-3, 3) {\textbf{Auth-Modul}\\Anmeldung, Registrierung\\OAuth2, Wiederherstellung};
+\node[module] (games) at (0, 3) {\textbf{Spiele-Modul}\\Blackjack, Slots\\Würfel, Coinflip};
+\node[module] (deposit) at (3, 3) {\textbf{Einzahlungs-Modul}\\Zahlungsintegration\\Stripe};
+\node[module] (home) at (6, 3) {\textbf{Home-Modul}\\Dashboard\\Benutzerprofil};
+
+% Service-Schicht - kompakter
+\node[service] (auth-svc) at (-4.5, 0.5) {\textbf{Auth Service}\\JWT-Verwaltung\\Benutzerstatus};
+\node[service] (user-svc) at (-1.5, 0.5) {\textbf{User Service}\\Profilverwaltung\\Guthaben-Updates};
+\node[service] (game-svc) at (1.5, 0.5) {\textbf{Spiele-Services}\\API-Kommunikation\\Spiellogik};
+\node[service] (payment-svc) at (4.5, 0.5) {\textbf{Payment Service}\\Stripe-Integration\\Einzahlungen};
+
+% Guards und Interceptors - kompakter
+\node[guard] (auth-guard) at (-1.5, -1.5) {\textbf{Auth Guard}\\Routen-Schutz};
+\node[guard] (http-interceptor) at (1.5, -1.5) {\textbf{HTTP Interceptor}\\JWT-Injection\\CORS-Headers};
+
+% Relationships
+\draw (app) -- (shared);
+\draw (app) -- (auth);
+\draw (app) -- (games);
+\draw (app) -- (deposit);
+\draw (app) -- (home);
+
+\draw (auth) -- (auth-svc);
+\draw (games) -- (game-svc);
+\draw (deposit) -- (payment-svc);
+\draw (home) -- (user-svc);
+
+\draw (auth-guard) -- (auth-svc);
+\draw (http-interceptor) -- (auth-svc);
+
+\end{tikzpicture}
+\end{landscape}
+
+\subsubsection{Architektur-Zusammenfassung}
+Die Casino Gaming Platform implementiert eine moderne, mehrschichtige Architektur, die folgende Prinzipien befolgt:
+
+\begin{itemize}
+    \item \textbf{Separation of Concerns:} Klare Trennung zwischen Präsentations-, Geschäftslogik- und Datenschicht
+    \item \textbf{Modularität:} Feature-basierte Modularisierung sowohl im Frontend als auch Backend
+    \item \textbf{Skalierbarkeit:} Container-basierte Architektur ermöglicht horizontale Skalierung
+    \item \textbf{Sicherheit:} Umfassende Sicherheitskonzepte mit JWT, OAuth2 und CORS-Schutz
+    \item \textbf{Wartbarkeit:} Standardisierte Patterns (MVC, Repository, Service Layer) erleichtern die Wartung
+\end{itemize}
+
+Die C4-Darstellung zeigt die Architektur auf verschiedenen Abstraktionsebenen und ermöglicht es unterschiedlichen Stakeholdern, die für sie relevanten Aspekte zu verstehen - von der Geschäftslogik bis hin zu technischen Implementierungsdetails.
+
+\subsubsection{Frontend-Paketstruktur (Detailansicht)}
+Die detaillierte Paketstruktur des Frontend zeigt die modulare Organisation:
 
 \dirtree{%
 .1 app/feature/.