Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/okanx68/sqs-project
Brewery Explorer ist eine Webanwendung, die Informationen über Brauereien in einer bestimmten Stadt bereitstellt, einschließlich Adresse, Telefonnummer und Link zur Webseite. Dieses Projekt nutzt Quarkus für das Backend, Angular für das Frontend und PostgreSQL als Datenbank.
https://github.com/okanx68/sqs-project
angular docker github-actions postgresql quarkus
Last synced: 3 days ago
JSON representation
Brewery Explorer ist eine Webanwendung, die Informationen über Brauereien in einer bestimmten Stadt bereitstellt, einschließlich Adresse, Telefonnummer und Link zur Webseite. Dieses Projekt nutzt Quarkus für das Backend, Angular für das Frontend und PostgreSQL als Datenbank.
- Host: GitHub
- URL: https://github.com/okanx68/sqs-project
- Owner: Okanx68
- License: mit
- Created: 2024-03-25T08:01:51.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-06-23T13:22:11.000Z (3 months ago)
- Last Synced: 2024-09-30T05:22:22.303Z (3 days ago)
- Topics: angular, docker, github-actions, postgresql, quarkus
- Language: JavaScript
- Homepage:
- Size: 12.6 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Brewery Explorer
**Software-Qualitätssicherung SoSe 2024**
# Setup
### Vorraussetzungen
* Git
* Docker
### Anwendung klonen
Das Projekt-Repository kann mit dem folgenden Befehl auf den lokalen Rechner geklont werden:
```bash
git clone https://github.com/Okanx68/sqs-project.git
cd sqs-project
```
### Projekt mit Docker Compose starten
Um das Projekt mit Docker Compose zu starten, muss im Stammverzeichnis folgender Befehl ausgeführt werden:
```bash
docker-compose up
```
Dieser Befehl lädt die erforderlichen Docker-Images aus der Projekt-Registry und startet die in der `docker-compose.yml`-Datei definierten Docker-Container.
### Anwendung aufrufen
Sobald das Backend, die Datenbank als auch das Frontend ausgeführt werden, kann die Anwendung im Webbrowser unter `http://localhost:4200` aufgerufen werden. Das Frontend kommuniziert mit dem Backend, welches unter `http://localhost:8080` läuft.
Die OpenAPI-Dokumentation des Backends kann über folgenden Link aufgerufen werden: http://localhost:8080/api/v1/q/swagger-ui
## SonarCloud
Die Ergebnisse der statischen Code-Analyse sind über SonarCloud verfügbar und können unter folgendem Link eingesehen werden: [SonarCloud-Analyse](https://sonarcloud.io/organizations/sqs-project/projects)
### Backend-Analyse
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-backend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-backend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-backend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-backend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-backend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-backend)
### Frontend-Analyse
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-frontend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-frontend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-frontend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-frontend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-frontend)
[](https://sonarcloud.io/summary/new_code?id=sqs-project_sqs-frontend)
# Einführung und Ziele
Das Ziel der Brewery Explorer Webanwendung ist es, Brauereien in einer bestimmten Stadt sowie deren Informationen wie beispielsweise Adresse, Telefonnummer oder Link zur Webseite abzurufen. Um die Effizienz der Anfragen zu verbessern, wird eine gezielte Caching-Strategie angewendet. Dafür setze ich Quarkus als Backend-Framework, Angular für das Frontend und PostgreSQL als Datenbank ein. Die benötigten Brauereiinformationen werden von der Open Brewery DB API (https://openbrewerydb.org) abgerufen und in der Datenbank, die hierbei als Cache dient, für erneute Anfragen abgespeichert. Die Suche nach Brauereien erfolgt durch die Eingabe des Stadtnamens mithilfe einer benutzerfreundlichen Weboberfläche.
## Aufgabenstellung
[Assignment Details SQS 2024](https://github.com/Okanx68/sqs-project/blob/main/doc/images/Assignment%20Details%20SQS2024.png)
## Qualitätsziele
| Qualitätskriterium | Beschreibung | Ziele | Maßnahmen |
|---------------------|---------------|-------|-----------|
| **Reliability - Zuverlässigkeit** | Die Fähigkeit der Anwendung, stabil und fehlerfrei zu laufen, selbst bei unerwarteten Eingaben und hoher Last. | - Resiliente Verarbeitung von Benutzereingaben
- Hohe Stabilität bei starker Nutzung | - Umfangreiche Testabdeckung mit Unit-Tests
- Lasttests mit Artillery
- Integrationstest|
| **Portability - Übertragbarkeit** | Flexibilität der Anwendung in Bezug auf die Laufzeitumgebung. |- Externe Abhängigkeiten verringern
- Ressourcen effizient nutzen
-Browserunabhängige Nutzbarkeit | - Containerisierung mithilfe von Docker zur Isolierung der Laufzeitumgebungen sowie Sicherstellung der Plattformunabhängigkeit
- Docker-Compose-Datei zum Starten der Services
- End-to-End-Tests mit Playwright |
| **Usability - Benutzerfreundlichkeit** | Einfache Interaktion mit der Benutzeroberfläche. | - Simple Bedienung
- Übersichtliche Weboberfläche | - End-to-End-Tests mit Playwright
- UI-Tests |
## Stakeholder
| Rolle | Kontakt | Erwartungshaltung |
|--------------|----------------|-------------------|
| Dozent | Beneken, Gerd ([email protected]) | "Will ein funktionierendes und gutes Projekt sehen!" |
| Dozent | Reimer, Mario-Leander ([email protected]) | "Will ein funktionierendes und sehr gutes Projekt sehen!" |
| Entwickler | Karaoglan, Okan ([email protected]) | "Will ein funktionierendes und sehr gutes Projekt entwickeln!" |
# Randbedingungen
## Technische Randbedingungen
* Das Projekt besteht aus einem Frontend, einem Backend, einer Datenbank und einer externen API
* GitHub wird als Code-Repository für die Versionierung und Verwaltung des Codes genutzt
* Zur Datenbeschaffung wird eine externe API verwendet
* Die Datenbank dient als Cache bzw. Zwischenspeicher für die Daten
* Das Backend speichert die Daten der externen API in der Datenbank
* Im Frontend kann der Benutzer einen Suchbegriff eingeben
* Nach Eingabe eines Suchbegriffs im Frontend wird zunächst in der Datenbank nach einem Eintrag gesucht
* Die externe API wird nur angesprochen, wenn kein Eintrag in der Datenbank existiert
* Die gefundenen Daten werden im Frontend visuell dargestellt
* Der eigens geschriebene Code wird umfassend getestet, einschließlich Last-, Integrations-, Unit-, UI- sowie End-to-End-Tests
* Eine CI/CD-Pipeline wird implementiert, die den Code nach jedem Push automatisch baut, testet und bereitstellt
* Der Code wird zusätzlich durch statische Code-Analyse in der Pipeline geprüft
* Alle Services werden als Docker-Container bereitgestellt
* Die Docker-Container werden nach jedem Push in der Pipeline neu gebaut und in der Registry abgelegt
* Über eine Docker-Compose-Datei können die Docker-Container gestartet werden
* Die Projektdokumentation wird im arc42-Format erstellt
## Organisatorische Randbedingungen
* **Abgabe des Projekts**: Sonntag, 23.06.2024
* **Projektdauer**: ein Semester
* **Projektdurchführung**: in Einzelarbeit
# Kontextabgrenzung
## Fachlicher Kontext
| Kommunikationsbeziehung | Eingabe | Ausgabe |
|------------------------------------|-----------------------------------------|----------------------------------------|
| User -> Brewery Explorer | Eingabe des Stadtnamens | Aktualisierung der Benutzeroberfläche |
| Brewery Explorer -> User | - | Anzeige der Brauereiinformationen |
| Brewery Explorer -> Open Brewery DB| Suchanfrage mit Stadtnamen | - |
| Open Brewery DB -> Brewery Explorer| - | Rückgabe der Brauereidaten |
## Technischer Kontext
Das System interagiert mit der externen Open Brewery DB API, um Brauereiinformationen im Quarkus-Backend abzurufen. Diese Daten werden in der PostgreSQL-Datenbank zwischengespeichert und Benutzern über die Angular-Webanwendung zugänglich gemacht.
### UML Deployment Diagramm
| Technischer Kanal | Eingabe | Ausgabe |
|------------------------------------|----------------------------------------------|----------------------------------------|
| User -> Angular Application | Benutzeraktionen (z.B. Stadtnamen) | Aktualisierte Benutzeroberfläche |
| Angular Frontend -> BreweryDataResource | HTTP Request (Stadtnamen) | HTTP Response (Brauereidaten) |
| BreweryDataResource -> BreweryDataController | API Call | Ergebnis der Datenabfrage |
| BreweryDataController -> BreweryDBService | API Request (Stadtnamen) | API Response (Brauereidaten) |
| BreweryDBService -> Open Brewery DB | API Request (Stadtnamen) | Liste der Brauereien |
| Open Brewery DB -> BreweryDBService | - | Brauereiinformationen |
| BreweryDataController -> BreweryData | Datenabfrage | Daten speichern/abrufen |
| BreweryData -> PostgreSQL | SQL Query | SQL Response |
| BreweryDataController -> BreweryDataDTO | Datenkonvertierung | DTO |
| BreweryDataResource -> Angular Application | HTTP Response | Aktualisierte Benutzeroberfläche |
### Schnittstelle zum Backend
Die '*BreweryDataResource*' Schnittstelle im Backend bietet die einfache Möglichkeit, eine Liste von Brauereien mit Informationen wie beispielsweise Adresse, Telefonnummer oder Link zur Webseite für eine bestimmte Stadt zurückzugeben.
* GET `/api/v1/breweries/{cityName}`: Dies ist der Endpunkt, um die Liste der Brauereien abzurufen. Der Pfadparameter {cityName} wird dabei durch den Stadtnamen ersetzt.
Parameter:
* cityName*: Der Name der Stadt, welche für die Suche der Brauereien benötigt wird. Dabei handelt es sich um einen Pfadparameter vom Typ String. Zum Beispiel: "Austin".
* count*: Die maximale Anzahl an Brauereien, die abgerufen und zwischengespeichert werden sollen. Dabei handelt es sich um einen Queryparameter vom Typ Integer. Von der Angular-Webanwendung aus werden standardmäßig maximal 20 Brauereien abgerufen.
Responses:
* 200 Success: Erfolgreiche Antwort, die eine Liste der Brauereien in einer jeweiligen Stadt zurückgibt.
* 204 No Content: Es wurden keine Brauereien gefunden.
* 400 Bad Request: Invalide Parameter.
* 404 Not Found: Die angeforderte Ressource wurde nicht gefunden.
* 500 Internal Server Error: Interner Serverfehler.
* Media Type: Die Antwort ist im JSON-Format ('application/json').
Die API-Dokumentation wird mittels Swagger UI bereitgestellt: http://localhost:8080/api/v1/q/swagger-ui
Die OpenAPI-Spezifikation des Backends kann mit folgendem Link im JSON-Format abgerufen werden: http://localhost:8080/api/v1/q/openapi?format=json
### Externe technische Schnittstelle - Open Brewery DB
Externe REST-API, die Brauereiinformationen basierend auf Stadtnamen zurückgibt. Der '*BreweryDBService*' kommuniziert direkt mit dieser API, um die Daten abzurufen und an den '*BreweryDataController*' weiterzugeben.
* GET https://api.openbrewerydb.org/v1/breweries: Dies ist der externe Endpunkt, über den die Liste der Brauereien abgerufen werden, wenn kein Eintrag im Cache zwischengespeichert ist.
Parameter:
* by_city: Der Name der Stadt als Queryparamter, für die eine Liste an Brauereien im JSON-Format zurückgegeben werden sollen.
* per_page: Die maximale Anzahl an Brauereien als Queryparameter (standardmäßig maximal 20 Brauereien).
API-Dokumentation des externen Endpunkts: https://openbrewerydb.org/documentation#list-breweries
### Mapping fachlicher auf technische Schnittstellen
- **Fachliche Eingabe: Stadtnamen** -> **Technische Schnittstelle: HTTP Request von der Angular Application an BreweryDataResource**
- **Fachliche Ausgabe: Brauereidaten** -> **Technische Schnittstelle: HTTP Response von BreweryDataResource an die Angular Application**
# Lösungsstrategie
Die zentrale Entwurfsstrategie dieses Projekts basiert auf mehreren wichtigen Technologieentscheidungen und Systementwürfen, die auf die spezifischen Aufgabenstellungen, Qualitätsziele und Randbedingungen abgestimmt sind.
## Technologieentscheidungen
Für das Backend wurde Quarkus als Framework ausgewählt. Quarkus bietet schnelle Startzeiten, eine nahtlose Integration mit Container-Technologien wie Docker und ist besonders gut für Microservice-Architekturen geeignet, was den Anforderungen an Performance und Skalierbarkeit gerecht wird. Angular wurde als Frontend-Framework gewählt, da es eine robuste Plattform für die Entwicklung dynamischer Single-Page-Anwendungen bietet und eine intuitive Benutzeroberfläche ermöglicht. PostgreSQL dient als Datenbank und wurde aufgrund seiner Zuverlässigkeit, Leistungsfähigkeit und Erweiterbarkeit ausgewählt. Die Datenbank wird als Cache für die Daten der externen API genutzt. Zur Beschaffung von Brauereiinformationen wird die Open Brewery DB API verwendet, da sie eine umfassende Datenquelle für die benötigten Informationen bietet.
## Top-Level-Zerlegung des Systems
Das System folgt einer Microservices-Architektur, bei der mehrere lose gekoppelte Dienste jeweils spezifische Funktionalitäten bereitstellen. Diese Architektur ermöglicht eine einfachere Wartung, Skalierung und Weiterentwicklung der einzelnen Komponenten. Zudem werden alle Services als Docker-Container bereitgestellt, was für isolierte Laufzeitumgebungen und Plattformunabhängigkeit sorgt und die Bereitstellung und Skalierung mithilfe einer Docker-Compose-Datei erleichtert.
## Qualitätsanforderungen
Ein zentraler Aspekt der Entwurfsstrategie ist die Sicherstellung der **Zuverlässigkeit (Reliability)** der Anwendung. Diese umfasst die Fähigkeit der Anwendung, stabil und fehlerfrei zu laufen, selbst bei unerwarteten Eingaben und hoher Last. Um diese Ziele zu erreichen, wird eine resiliente Verarbeitung von Benutzereingaben und eine hohe Stabilität bei starker Nutzung angestrebt. Maßnahmen zur Erreichung dieser Ziele umfassen eine umfangreiche Testabdeckung mit Unit-Tests, Lasttests mit Artillery sowie Integrationstests.
Ein weiteres wichtiges Qualitätsziel ist die **Übertragbarkeit (Portability)** der Anwendung. Dies bezieht sich auf die Flexibilität der Anwendung in Bezug auf die Laufzeitumgebung. Um dies zu gewährleisten, sollen externe Abhängigkeiten verringert und die Ressourcennutzung effizient gestaltet werden. Hierfür wird die Containerisierung mithilfe von Docker eingesetzt, um isolierte Laufzeitumgebungen zu schaffen und die Plattformunabhängigkeit sicherzustellen. Eine Docker-Compose-Datei wird bereitgestellt, um die Verwaltung und Orchestrierung der verschiedenen Docker-Container zu erleichtern. End-to-End-Tests mit Playwright gewährleisten, dass die Anwendung auf verschiedenen Browsern einwandfrei funktioniert, was die browserunabhängige Nutzbarkeit sicherstellt.
Darüber hinaus spielt die **Benutzerfreundlichkeit (Usability)** eine entscheidende Rolle. Eine einfache Interaktion mit der Benutzeroberfläche ist essentiell. Die Ziele hierbei sind eine simple Bedienung und eine übersichtliche Weboberfläche. Maßnahmen zur Erreichung dieser Ziele umfassen End-to-End-Tests mit Playwright und UI-Tests, um eine optimale Benutzererfahrung zu gewährleisten.
## Organisatorische Entscheidungen
Ein wesentlicher Bestandteil der organisatorischen Entscheidungen in diesem Projekt ist die Implementierung einer CI/CD-Pipeline mithilfe von GitHub Actions um für eine hohe Qualität und Zuverlässigkeit des Codes zu sorgen. Diese Pipeline automatisiert den gesamten Prozess vom Code-Commit bis zur Bereitstellung und gewährleistet eine kontinuierliche Integration und Auslieferung neuer Funktionen und Verbesserungen. Bei jedem Push oder Pull-Request wird der Code automatisch gebaut und durch eine Reihe automatisierter Tests, einschließlich Unit-, Integrations- und End-to-End-Tests, geprüft. Zusätzlich werden Frontend-Tests durchgeführt, um sicherzustellen, dass die Benutzeroberfläche den Erwartungen entspricht. ArchUnit-Tests werden im Backend verwendet, um die Einhaltung von Architekturregeln zu überprüfen. Die Dockerfiles werden in der Pipeline gelintet, um sicherzustellen, dass sie syntaktisch korrekt und effizient geschrieben sind. SonarCloud ergänzt als statisches Code-Analyse-Tool die Tests, um sicherzustellen, dass der Code den Qualitätsstandards entspricht. Nach erfolgreichem Bestehen aller Tests werden Docker-Container erstellt und in einer Registry gespeichert. Diese Container können dann in die verschiedenen Umgebungen mithilfe der Docker-Compose-Datei bereitgestellt werden. Um die Leistungsfähigkeit und Stabilität der Anwendung unter hoher Last zu gewährleisten, werden zudem automatisierte Lasttests mit Artillery durchgeführt.
# Bausteinsicht
## Whitebox Gesamtsystem
**Übersichtsdiagramm**
**Begründung**
Die Zerlegung des Gesamtsystems in Bausteine folgt den Prinzipien der Modularität und der Verantwortlichkeitstrennung. Dadurch wird die Wartbarkeit und Erweiterbarkeit des Systems verbessert.
**Enthaltene Bausteine**
| Name | Verantwortung |
|--------------------|----------------------------------------------|
| Angular-Frontend | Bereitstellungg der Benutzeroberfläche |
| Quarkus-Backend | Verarbeitung der Geschäftslogik und Bereitstellung der API-Endpunkte |
| PostgeSQL-Datenbank | Speicherung und Verwaltung der Daten |
| Open Brewery DB API | Externe Quelle für Brauereiinformationen |
**Wichtige Schnittstellen**
| Schnittstelle | Beschreibung |
|--------------------|----------------------------------------------|
| Frontend-Backend | Schnittstelle für die Kommunikation zwischen Angular-Frontend und Quarkus-Backend |
| Backend-Datenbank | Schnittstelle für die Kommunikation zwischen Quarkus-Backend und PostgreSQL-Datenbank |
| Backend-Externe-API | Schnittstelle für die Kommunikation zwischen Quarkus-Backend und Open Brewery DB API |
### Angular-Frontend
**Zweck/Verantwortung**
Das Angular-Frontend ist verantwortlich für die Bereitstellung der Benutzeroberfläche, über die Benutzer nach Brauereien suchen und Informationen anzeigen können.
**Schnittstelle**
* HTTP GET `api/v1/breweries/{cityName}`: Schnittstelle zur Abfrage von Brauereiinformationen basierend auf dem Stadtnamen.
### Quarkus-Backend
**Zweck/Verantwortung**
Das Quarkus-Backend verarbeitet die Geschäftslogik und stellt API-Endpunkte zur Verfügung, über die das Frontend und andere externe Systeme auf die Anwendung zugreifen können.
**Schnittstellen**
* HTTP GET `api/v1/breweries/{cityName}`: Endpunkt zur Abfrage von Brauereiinformationen.
* JDBC: Schnittstelle zur Kommunikation mit der PostgreSQL-Datenbank.
### PostgreSQL-Datenbank
**Zweck/Verantwortung**
Die PostgreSQL-Datenbank speichert und verwaltet alle Daten, die von der Anwendung benötigt werden, einschließlich der gecachten Brauereiinformationen.
**Schnittstelle**
* JDBC: Schnittstelle zur Kommunikation mit dem Quarkus Backend.
### Open Brewery DB API
**Zweck/Verantwortung**
Die Open Brewery DB API dient als externe Quelle für Brauereiinformationen und wird vom Backend verwendet, um Daten abzurufen, die nicht im lokalen Cache verfügbar sind.
**Schnittstelle**
* HTTP GET `https://api.openbrewerydb.org/v1/breweries?by_city={cityName}&per_page={count}`: Endpunkt zur Abfrage von Brauereiinformationen basierend auf dem Stadtnamen und der maximalen Anzahl an Brauerein.
## Ebene 1
### Whitebox Quarkus-Backend
**Übersichtsdiagramm**
**Enthaltene Bausteine**
| Name | Verantwortung |
|--------------------|----------------------------------------------|
| BreweryDataResource | Bereitstellung der API-Endpunkte zur Abfrage von Brauereidaten |
| BreweryDataController | Geschäftslogik zur Verarbeitung von Brauereianfragen |
| BreweryDBService | Kommunikation mit der Open Brewery DB API |
| BreweryData | Datenmodell für Brauereidaten sowie Kommunikation mit der Datenbank |
| BreweryDataDTO | Datenübertragungsobjekt für Brauereiinformationen |
### Whitebox Angular-Frontend
**Übersichtsdiagramm**
**Enthaltene Bausteine**
| Name | Verantwortung |
|--------------------|----------------------------------------------|
| AppComponent | Bereitstellung der Weboberfläche (Suchfunktion sowie Anzeige der Liste von Brauerein) |
| BreweryService | Kommunikation mit dem Backend zur Abfrage von Brauerdaten |
| BreweryModel | Datenmodell für Brauereidaten |
# Laufzeitsicht
## Szenario 1: Abruf von Brauereiinformationen (Cache-Hit)
### Ablaufbeschreibung
1. **Benutzeranfrage im Frontend**: Ein Benutzer navigiert auf der Angular-basierten Webanwendung und gibt den Namen einer Stadt ein, um Informationen zu Brauereien abzurufen.
2. **Anfrage an das Backend**: Das Frontend sendet eine HTTP GET-Anfrage an das Quarkus-Backend. Der Endpunkt ist `/api/v1/breweries/{cityName}`.
3. **Überprüfung des Caches im Backend**: Das Backend prüft, ob die Brauereiinformationen für die angefragte Stadt bereits im Cache (PostgreSQL-Datenbank) vorhanden sind.
4. **Cache-Hit**: Wenn die Informationen im Cache vorhanden sind, werden diese aus dem Cache an das Backend gesendet.
5. **Antwort an das Frontend**: Das Backend sendet die Brauereiinformationen an das Frontend.
6. **Anzeige der Daten**: Das Frontend zeigt die erhaltenen Baustelleninformationen dem Benutzer an.
### Laufzeitdiagramm
## Szenario 2: Abruf von Brauereiinformationen (Cache-Miss)
### Ablaufbeschreibung
1. **Benutzeranfrage im Frontend**: Ein Benutzer navigiert auf der Angular-basierten Webanwendung und gibt den Namen einer Stadt ein, um Informationen zu Brauereien abzurufen.
2. **Anfrage an das Backend**: Das Frontend sendet eine HTTP GET-Anfrage an das Quarkus-Backend. Der Endpunkt ist `/api/v1/breweries/{cityName}`.
3. **Überprüfung des Caches im Backend**: Das Backend prüft, ob die Brauereiinformationen für die angefragte Stadt bereits im Cache (PostgreSQL-Datenbank) vorhanden sind.
4. **Cache-Miss**: Wenn die Informationen nicht im Cache vorhanden sind, wird eine Anfrage an die externe API der Open Brewery DB gesendet.
5. **Anfrage and die API der Open Brewery DB**: Das Backend sendet eine HTTP GET-Anfrage an die API der Open Brewery DB, um die Brauereiinformationen für die angefragte Stadt abzurufen.
6. **Empfang und Speicherung der Daten**: Die API der Open Brewery DB liefert die Daten im JSON-Format zurück. Das Backend speichert diese Daten im Cache (PostgreSQL-Datenbank).
7. **Antwort an das Frontend**: Das Backend sendet die Brauereiinformationen an das Frontend.
8. **Anzeige der Daten**: Das Frontend zeigt die erhaltenen Baustelleninformationen dem Benutzer an.
### Laufzeitdiagramm
## Szenario 3: Fehlgeschlagener Abruf von Brauereiinformationen (falscher Stadtnamen)
### Ablaufbeschreibung
1. **Benutzeranfrage im Frontend**: Ein Benutzer navigiert auf der Angular-basierten Webanwendung und gibt den Namen einer Stadt ein, um Informationen zu Brauereien abzurufen.
2. **Anfrage an das Backend**: Das Frontend sendet eine HTTP GET-Anfrage an das Quarkus-Backend. Der Endpunkt ist `/api/v1/breweries/{cityName}`.
3. **Überprüfung des Caches im Backend**: Das Backend prüft, ob die Brauereiinformationen für die angefragte Stadt bereits im Cache (PostgreSQL-Datenbank) vorhanden sind.
4. **Cache-Miss**: Wenn die Informationen nicht im Cache vorhanden sind, wird eine Anfrage an die externe API der Open Brewery DB gesendet.
5. **Anfrage and die API der Open Brewery DB**: Das Backend sendet eine HTTP GET-Anfrage an die API der Open Brewery DB, um die Brauereiinformationen für die angefragte Stadt abzurufen.
6. **Fehlerantwort von der API der Open Brewery DB**: Die API der Open Brewery DB liefert keine Brauereiinformationen zurück.
7. **Antwort an das Frontend**: Das Backend sendet eine Fehlerantwort an das Frontend, um den Benutzer über den Fehler zu informieren.
8. **Anzeige der Daten**: Das Frontend zeigt eine entsprechende Fehlermeldung dem Benutzer an ("City not found. Try again.").
### Laufzeitdiagramm
# Verteilungssicht
## Infrastruktur
**Begründung**
Das System wird in einer Container-Umgebung mittels einer Docker-Compose-Datei betrieben, um eine einfache Skalierbarkeit, Portabilität und Konsistenz zu gewährleisten. Docker-Container werden verwendet, um die einzelnen Komponenten des Systems zu isolieren und zu verwalten.
**Qualitäts- und/oder Leistungsmerkmale**
* **Skalierbarkeit**: Durch den Einsatz von Docker-Containern kann das System leicht horizontal skaliert werden, indem zusätzliche Container bei Bedarf gestartet werden.
* **Portabilität**: Docker gewährleistet, dass die Anwendung in verschiedenen Umgebungen gleich läuft, was die Portabilität zwischen Entwicklungs-, Test- und Produktionsumgebungen verbessert.
* **Isolation**: Jeder Dienst läuft in seinem eigenen Container, was die Isolation und damit die Stabilität und Sicherheit des Systems erhöht.
* **Wiederholbarkeit**: Die Verwendung von Docker Compose ermöglicht eine einfache und wiederholbare Bereitstellung der gesamten Systemumgebung.
**Zuordnung von Bausteinen zu Infrastruktur**
| Baustein | Infrastruktur |
|--------------------|----------------------------------------------|
| Frontend-Container | Docker-Container "sqs_frontend" wird bereitgestellt auf Nginx-Container "nginx:alpine" |
| Backend-Container | Docker-Container "sqs_backend" wird bereitsgestellt auf JVM-Container "registry.access.redhat.com/ubi8/openjdk-17:1.18" |
| PostgeSQL-Datenbank | Docker-Container "sqs_pg_compose" wird bereitgestellt auf Datenbank-Container "postgres:14" |
| Open Brewery DB API | Externer Service |
**Docker-Compose-Datei**
In diesem Projekt genutzte Docker-Compose-Datei: [*\*](https://github.com/Okanx68/sqs-project/blob/main/docker-compose.yml)
Die Images für das Front- und Backend werden aus der GitHub-Registry des Projektes gezogen.
+-------------------------+ +---------------------------+ +----------------------------+
| | | | | |
| db |---------->| backend |---------->| frontend |
| postgres:14 | | sqs_backend | | sqs_frontend |
| Port: 5432 | | Ports: 8080 | | Port: 4200 |
| Volumes: | | Depends on: db | | Depends on: backend |
| postgres_data | | | | |
| | | | | |
+-------------------------+ +---------------------------+ +----------------------------+
# Querschnittliche Konzepte
## Backend UML-Klassendiagramm
## GitHub Actions
In diesem Projekt verwendete Pipeline: [*\*](https://github.com/Okanx68/sqs-project/blob/main/docker-compose.yml)
```
+---------------------+ +---------------------------+
| lint_dockerfiles |-------->| build_analyze_push |
| - Lint Backend | | - Build backend |
| Dockerfile | | - Build frontend |
| - Lint Frontend | | - Run SonarCloud Analysis |
| Dockerfile | | - Push Docker images |
+---------------------+ +-----------+---------------+
|
v
+------------+-------------+
| |
+-----------------------+ +------------------------+
| artillery_test | | end-to-end-tests |
| - Start Docker Compose| | - Start Docker Compose |
| - Run Artillery Tests | | - Run Playwright Tests |
+-----------------------+ +------------------------+
```
## Artillery & Playwright
Lasttest-Skript: [*\*](https://github.com/Okanx68/sqs-project/blob/main/artillery-tests/artillery.yml)
End-to-End-Tests: [*\*](https://github.com/Okanx68/sqs-project/blob/main/playwright/tests/homepage.spec.js)
## SonarCloud
Statische Code-Analyse für Front- und Backend: [*\*](https://sonarcloud.io/organizations/sqs-project/projects)
# Architekturentscheidungen
Die Architekturentscheidungen für dieses Projekt wurden sorgfältig getroffen, um eine robuste, skalierbare und wartbare Anwendung zu gewährleisten.
## Technologiewahl
Folgende Technologien wurden in diesem Projekt eingesetzt:
* **Quarkus**: Für das Backend wurde Quarkus ausgewählt, ein Framework, das sich durch schnelle Startzeiten und geringe Ressourcenanforderungen auszeichnet. Es ist besonders geeignet für Cloud-native und Microservice-Architekturen und ermöglicht eine nahtlose Integration mit Container-Technologien wie Docker.
* **Angular**: Angular dient als Frontend-Framework. Es bietet eine leistungsstarke Plattform für die Entwicklung dynamischer Single-Page-Anwendungen und unterstützt eine intuitive Benutzeroberfläche.
* **PostgreSQL**: Als Datenbank wurde PostgreSQL gewählt, um von seiner Zuverlässigkeit, Leistungsfähigkeit und Erweiterbarkeit zu profitieren. Die Datenbank wird als Cache für die Daten der externen API verwendet.
* **Open Brewery DB API**: Zur Beschaffung von Brauereiinformationen wird die Open Brewery DB API genutzt, die eine umfassende und zuverlässige Datenquelle bietet.
* **Docker**: Die Anwendung wurde mit Docker containerisiert, um isolierte Laufzeitumgebungen zu schaffen und die Plattformunabhängigkeit sicherzustellen.
* **Docker Compose**: Zur Verwaltung der Container wurde Docker Compose eingesetzt, um die Container-Orchestrierung zu erleichtern.
* **GitHub Actions**: Es wurden automatisierte CI/CD-Pipelines mit GitHub Actions eingerichtet, die das Bauen, Testen und Bereitstellen der Anwendung automatisieren. Dazu gehören auch statische Code-Analysen mit SonarCloud und das Bereitstellen der Docker-Container in einer Registry.
* **SonarCloud**: SonarCloud wurde zur statischen Code-Analyse verwendet, um die Codequalität zu überwachen und potenzielle Sicherheitslücken und Bugs frühzeitig zu identifizieren.
* **Playwright**: End-to-End-Tests wurden mit Playwright durchgeführt, um die Funktionalität der gesamten Anwendung sicherzustellen.
* **Artillery**: Für Lasttests wurde Artillery verwendet, um die Leistungsfähigkeit und Stabilität der Anwendung unter hoher Last zu überprüfen.
* **JUnit**: JUnit wurde für Unit- und Integrationstests genutzt, um die Qualität und Korrektheit des Codes sicherzustellen.
* **ArchUnit**: ArchUnit wurde genutzt, um Architektur- und Design-Prinzipien im Backend zu überprüfen, sicherzustellen und durchzusetzen. Dies unterstützt die langfristige Wartbarkeit und Konsistenz des Codes.
* **Hadolint**: Hadolint wurde verwendet, um die Dockerfiles zu linten und sicherzustellen, dass sie syntaktisch korrekt und nach bewährten Methoden geschrieben sind.
* **OpenAPI**: OpenAPI wurde verwendet, um die API-Spezifikationen des Backends zu definieren. Dies ermöglicht eine klare und standardisierte Beschreibung der API-Endpunkte, Parameter und Rückgabewerte.
* **Swagger**: Swagger wurde in Kombination mit OpenAPI eingesetzt, um eine interaktive API-Dokumentation zu generieren, die es Entwicklern und Testern erleichtert, die API zu verstehen und zu nutzen.
## Schichtenmodell
Das System wurde in mehreren Schichten organisiert, um eine klare Trennung von Präsentation, Geschäftslogik und Datenzugriff zu gewährleisten. Diese Struktur erhöht die Wartbarkeit und Skalierbarkeit der Anwendung. Im Detail besteht die Architektur aus folgenden Schichten:
* **Präsentationsschicht**: Diese Schicht umfasst das Angular-Frontend, das für die Benutzeroberfläche zuständig ist. Sie ermöglicht eine reaktive und benutzerfreundliche Interaktion mit dem System.
* **Geschäftslogikschicht**: Diese Schicht wird durch das Quarkus-Backend repräsentiert. Hier wird die Anwendungslogik implementiert, die die Geschäftsprozesse steuert und verarbeitet. Diese Schicht nimmt Anfragen vom Frontend entgegen, bearbeitet sie und kommuniziert mit der Datenzugriffsschicht, um die erforderlichen Daten zu erhalten oder zu speichern. ArchUnit-Tests werden hier verwendet, um sicherzustellen, dass die Architekturregeln in dieser Schicht eingehalten werden.
* **Datenzugriffsschicht**: Diese Schicht beinhaltet die Interaktionen mit der PostgreSQL-Datenbank. Sie kümmert sich um das Speichern, Abrufen und Verwalten der Daten. Die Datenbank dient auch als Cache für die Daten der externen API (Open Brewery DB).
## Entwicklungsprozess
Die Entwicklung des Projekts begann mit einem Backend-First Ansatz, um eine stabile Grundlage zu schaffen. Dieser Ansatz stellte sicher, dass die Geschäftslogik und Datenverwaltung solide implementiert wurden, bevor die Benutzeroberfläche entwickelt wurde. Nach der Fertigstellung und gründlichen Testung des Backends, das API- und Datenbankinteraktionen sicherstellt, wurde das Angular-Frontend entwickelt und nahtlos integriert.
Um eine hohe Qualität zu gewährleisten, wurden umfassende Tests durchgeführt, darunter Unit-Tests, Integrationstests, End-to-End-Tests mit Playwright sowie Lasttests mit Artillery. Diese Teststrategien stellten sicher, dass alle Systemkomponenten zuverlässig und performant zusammenarbeiten. ArchUnit-Tests wurden im Backend eingesetzt, um zusätzlich die Einhaltung von Architektur- und Designprinzipien zu überprüfen und sicherzustellen.
Die CI/CD-Pipeline, implementiert mit GitHub Actions, automatisierte den gesamten Prozess vom Code-Commit bis zur Bereitstellung. Diese Pipeline baute, testete und stellte die Anwendung bereit, wodurch kontinuierliche Integration und Auslieferung neuer Funktionen und Verbesserungen gewährleistet wurden. Zudem wurde eine statische Code-Analyse mit SonarCloud in der Pipeline durchgeführt, um die Codequalität zu überwachen und potenzielle Sicherheitslücken frühzeitig zu erkennen.
## Technologische Eigenschaften des Projekts
### Frontend
| Technologie | Version |
|----------------|-----------------|
| Angular | 17.3.11 |
| Node | 20.13.0 |
| Bootstrap | 5.3.3 |
### Backend
| Technologie | Version |
|----------------|-----------------|
| Quarkus | 3.9.1 |
| Maven | 3.8.6 |
| Java | 17 |
### Database
| Technologie | Version |
|----------------|-----------------|
| PostgreSQL | 14 |
### Testing
| Technologie | Version |
|----------------|-----------------|
| JUnit | 5 |
| ArchUnit | 1.3.0 |
| Artillery | latest |
| Playwright | latest |
# Qualitätsanforderungen
Ein zentraler Aspekt der Entwurfsstrategie ist die Sicherstellung der **Zuverlässigkeit (Reliability)** der Anwendung. Diese umfasst die Fähigkeit der Anwendung, stabil und fehlerfrei zu laufen, selbst bei unerwarteten Eingaben und hoher Last. Um diese Ziele zu erreichen, wird eine resiliente Verarbeitung von Benutzereingaben und eine hohe Stabilität bei starker Nutzung angestrebt. Maßnahmen zur Erreichung dieser Ziele umfassen eine umfangreiche Testabdeckung mit Unit-Tests, Lasttests mit Artillery sowie Integrationstests.
Ein weiteres wichtiges Qualitätsziel ist die **Übertragbarkeit (Portability)** der Anwendung. Dies bezieht sich auf die Flexibilität der Anwendung in Bezug auf die Laufzeitumgebung. Um dies zu gewährleisten, sollen externe Abhängigkeiten verringert und die Ressourcennutzung effizient gestaltet werden. Hierfür wird die Containerisierung mithilfe von Docker eingesetzt, um isolierte Laufzeitumgebungen zu schaffen und die Plattformunabhängigkeit sicherzustellen. Eine Docker-Compose-Datei wird bereitgestellt, um die Verwaltung und Orchestrierung der verschiedenen Docker-Container zu erleichtern. End-to-End-Tests mit Playwright gewährleisten, dass die Anwendung auf verschiedenen Browsern einwandfrei funktioniert, was die browserunabhängige Nutzbarkeit sicherstellt.
Darüber hinaus spielt die **Benutzerfreundlichkeit (Usability)** eine entscheidende Rolle. Eine einfache Interaktion mit der Benutzeroberfläche ist essentiell. Die Ziele hierbei sind eine simple Bedienung und eine übersichtliche Weboberfläche. Maßnahmen zur Erreichung dieser Ziele umfassen End-to-End-Tests mit Playwright und UI-Tests, um eine optimale Benutzererfahrung zu gewährleisten.
## Qualitätsbaum
## Qualitätsszenarien
| Attribut | Szenario | Maßnahme |
|------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
| Reliability - Zuverlässigkeit | Nutzungsszenario: Um die Zuverlässigkeit zu gewährleisten, wird das System umfassend getestet. | Unit-Tests, Integrationstests, End-to-End-Tests, Lasttests |
| | Änderungsszenario: Regelmäßige Aktualisierung des Testskonzepts bei einer Änderung im Code. | Umfassende Testabdeckung |
| | Nutzungsszenario: Das System bleibt unter hoher Last stabil und reagiert effizient. | Lasttests mit Artillery |
| | Änderungsszenario: Neue Anforderungen erfordern Anpassungen und erneute Tests der Systemstabilität. | Anpassung der Tests |
| Portability - Übertragbarkeit | Nutzungsszenario: Das System läuft in verschiedenen Docker-Containern auf unterschiedlichen Plattformen. | Containerisierung mit Docker, Nutzung von Docker Compose zur Orchestrierung |
| | Änderungsszenario: Neue Container-Umgebungen werden unterstützt und getestet. | Unabhängige Laufzeitumgebung |
| | Nutzungsszenario: Das System funktioniert in unterschiedlichen Browsern ohne Probleme. | End-to-End-Tests mit Playwright |
| | Änderungsszenario: Zukünftige Browser-Versionen werden unterstützt und getestet. | Regelmäßige Updates und Tests mit Playwright |
| Usability - Benutzerfreundlichkeit | Nutzungsszenario: Die Benutzer können intuitiv nach Brauereien suchen und die Ergebnisse anzeigen lassen. | Benutzerfreundliches UI-Design, einfache Navigation. End-to-End-Tests mit Playwright |
| | Änderungsszenario: Verbesserungen in der Benutzeroberfläche werden kontinuierlich umgesetzt. | Benutzerfeedback einholen und umsetzen, UI-Tests |
| | Nutzungsszenario: Das System zeigt relevante Informationen zu Brauereien klar und verständlich an. | Übersichtliches Layout, konsistente Darstellung der Daten |
| | Änderungsszenario: Neue Nutzeranforderungen and das Design werden kontinuierlich integriert. | Regelmäßige Überprüfung und Anpassung an Nutzeranforderungen |
# Risiken und technische Schulden
| Risiko/Technische Schuld | Beschreibung | Maßnahme zur Risikovermeidung/Risikominimierung/Abbau der technischen Schuld | Priorität |
|--------------------------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-----------|
| Sicherheitslücken | Potenzielle Sicherheitslücken in Datenbank, Backend und Frontend können die Anwendung gefährden. | Implementierung von Sicherheitsmechanismen wie OAuth2 oder Inputvalidierung und -sanitierung, regelmäßige Sicherheitsüberprüfungen, Umgebungsvariablen für Datenbankpasswörter implementieren | Hoch |
| Fehlende Testabdeckung | Unzureichende Tests, besonders im Bereich End-to-End-Tests und Lasttests, können zu Fehlern im System führen. | Ausbau einer umfassenden Teststrategie mit Unit-, Integrations-, Last- und End-to-End-Tests | Hoch |
| Mangelnde Skalierbarkeit | Das Quarkus-Backend könnte bei hoher Last an seine Grenzen stoßen. | Skalierungstechniken anwenden, horizontales Scaling unterstützen, Lasttests regelmäßig durchführen | Hoch |
| Performance-Probleme | Performanceprobleme bei hoher Last und großen Datenmengen könnten die Benutzererfahrung beeinträchtigen. | Optimierung von Caching-Mechanismen und Datenbankabfragen, Einsatz von Load Balancing | Mittel |
| Docker-Komplexität | Der gleichzeitige Betrieb von mehreren Docker-Containern (Backend, Frontend, Datenbank) kann komplex sein. | Automatisierte Einrichtung und Orchestrierung der Docker-Container, ausführliche Dokumentation | Mittel |
| Abhängigkeit von externer API | Verfügbarkeit und Zuverlässigkeit der Open Brewery DB API könnte die Systemstabilität beeinflussen. | Implementierung von Fallback-Mechanismen, optimierteres Caching der API-Daten, regelmäßige Überprüfung der API-Verfügbarkeit | Mittel |
| Komplexität der API-Kommunikation | Die Kommunikation zwischen Frontend und Backend via REST kann komplex und fehleranfällig sein. | ausführliches Testen der API-Endpunkte, Einsatz von API-Gateways | Mittel |
| Wartungsaufwand | Hoher Wartungsaufwand durch regelmäßige Updates und Anpassungen der Abhängigkeiten und Dockerfiles. | Automatisierung der Wartungsaufgaben, regelmäßige Überprüfung und Aktualisierung der Abhängigkeiten | Mittel |
| Dateninkonsistenz | Inkonsistenzen bei der Synchronisation der Daten zwischen der PostgreSQL-Datenbank und der externen API. | Implementierung von Datenintegritätsprüfungen, regelmäßige Datenabgleich- und Synchronisationsmechanismen | Mittel |
# Glossar
| Begriff | Definition |
|-------------------------|--------------------------------------------------------------------------------------------------------------|
| **Quarkus** | Ein Java-Framework, das schnelle Startzeiten und geringe Ressourcenanforderungen bietet, ideal für Cloud-native und Microservice-Architekturen. |
| **Angular** | Ein Frontend-Framework zur Entwicklung dynamischer Single-Page-Anwendungen mit einer intuitiven Benutzeroberfläche. |
| **PostgreSQL** | Eine relationale Datenbank, bekannt für ihre Zuverlässigkeit, Leistungsfähigkeit und Erweiterbarkeit, die als Cache verwendet wird. |
| **Open Brewery DB API** | Eine externe REST-API, die Brauereiinformationen basierend auf Stadtnamen bereitstellt. |
| **Docker** | Eine Containerisierungsplattform, die isolierte Laufzeitumgebungen und die Plattformunabhängigkeit gewährleistet. |
| **Docker Compose** | Ein Tool zur Definition und Ausführung mehrerer Docker-Container zur Orchestrierung der Anwendungsservices. |
| **GitHub Actions** | Ein CI/CD-Tool von GitHub, das automatisierte Workflows zum Bauen, Testen und Bereitstellen von Anwendungen ermöglicht. |
| **SonarCloud** | Ein statisches Code-Analyse-Tool zur Überwachung der Codequalität und frühzeitigen Identifikation von Sicherheitslücken und Bugs. |
| **Playwright** | Ein End-to-End-Testframework zur Sicherstellung der Funktionalität der gesamten Anwendung auf verschiedenen Browsern. |
| **Artillery** | Ein Lasttesttool zur Überprüfung der Leistungsfähigkeit und Stabilität der Anwendung unter hoher Last. |
| **JUnit** | Ein Framework für Unit- und Integrationstests in Java, das die Qualität und Korrektheit des Codes sicherstellt. |
| **ArchUnit** | Ein Tool zur Überprüfung von Architektur- und Design-Prinzipien im Backend, um die langfristige Wartbarkeit und Konsistenz des Codes zu unterstützen. |
| **Hadolint** | Ein Linter für Dockerfiles, der sicherstellt, dass sie syntaktisch korrekt und nach bewährten Methoden geschrieben sind. |
| **OpenAPI** | Eine Spezifikation zur Beschreibung von RESTful APIs, die eine klare und standardisierte Dokumentation der API-Endpunkte ermöglicht. |
| **Swagger** | Ein Open-Source-Tool zur Generierung interaktiver API-Dokumentationen basierend auf OpenAPI-Spezifikationen. |
| **Unit-Test** | Ein Test, der einzelne Softwarekomponenten isoliert überprüft, um deren korrekte Funktion sicherzustellen. |
| **Integrationstest** | Ein Test, der das Zusammenspiel mehrerer Komponenten überprüft, um deren korrekte Zusammenarbeit sicherzustellen. |
| **End-to-End-Test** | Ein Test, der das gesamte System von Anfang bis Ende aus der Benutzerperspektive überprüft. |
| **Lasttest** | Ein Testverfahren, das die Leistungsfähigkeit und Stabilität einer Anwendung unter hoher Last prüft, um sicherzustellen, dass das System auch bei Spitzenbelastungen effizient arbeitet. |
| **CI/CD-Pipeline** | Continuous Integration/Continuous Deployment-Pipeline, die den Prozess vom Code-Commit bis zur Bereitstellung automatisiert. |
| **Caching** | Eine Strategie zur Zwischenspeicherung von Daten, um die Effizienz und Geschwindigkeit von Anfragen zu verbessern. |
| **Microservices** | Eine Architektur, bei der die Anwendung in kleine, lose gekoppelte Dienste unterteilt ist, die unabhängig voneinander entwickelt und skaliert werden können. |
| **API-Gateway** | Ein Server, der als einheitlicher Einstiegspunkt für alle API-Aufrufe dient und verschiedene Services orchestriert. |
| **OAuth2** | Ein Autorisierungs-Framework, das sichere Zugriffstoken für API-Anfragen bereitstellt. |
| **Fallback-Mechanismus**| Ein Mechanismus, der alternative Verfahren aktiviert, wenn die primäre Methode fehlschlägt, um die Systemverfügbarkeit zu gewährleisten. |