Entwicklung eines Systems zur Erstellung, Pflege und Verwaltung von Architecture Decision Records (ADRs), das es Teams ermöglicht, Entscheidungen im Zusammenhang mit der Softwarearchitektur effizient zu dokumentieren, zu suchen und zu verfolgen. Das System soll eine intuitive Benutzeroberfläche bieten und die Möglichkeit zur Kategorisierung sowie zur Verfolgung von Abhängigkeiten zwischen Entscheidungen unterstützen.
Die Aufgabe ist so konzipiert, dass sie in einem Nettozeitrahmen von ca. 4-5 Stunden bearbeitet werden kann. Dies umfasst die Ideenfindung, die objektorientierte Analyse sowie das Design.
Um die Anforderungen zwischen Client und Server für das ADR-Verwaltungssystem zu definieren, erstelle einen OpenAPI Contract. Dieser Contract soll die Kernfunktionalitäten des Systems abbilden, einschließlich Endpunkten zum Erstellen, Abrufen, Aktualisieren und Löschen von Architecture Decision Records (ADRs). Zudem sollen Modelle für ADRs, Benutzer und Kommentare definiert und in den Components des Contracts spezifiziert werden. Die Modelle sind dann in den entsprechenden PATHs für die Bodies und andere Anfragen zu referenzieren.
Diese Skizzen dienen als vorläufige Entwürfe, die in der Analyse- und Designphase weiter verfeinert werden.
Für die Implementierung des Systems zur Verwaltung von Architecture Decision Records (ADRs) sind folgende Klassen essentiell:
@startuml
class ADR {
-id: int
-title: String
-date: Date
-status: DecisionStatus
-description: String
-rationale: String
-consequences: String
-alternatives: String
+createADR(): void
+updateADR(): void
+deleteADR(): void
}
class User {
-id: int
-name: String
-email: String
+createUser(): void
+updateUser(): void
+deleteUser(): void
}
class Category {
-id: int
-name: String
+createCategory(): void
+updateCategory(): void
+deleteCategory(): void
}
class Tag {
-id: int
-name: String
+createTag(): void
+updateTag(): void
+deleteTag(): void
}
class Comment {
-id: int
-text: String
-date: Date
-userId: int
+createComment(): void
+deleteComment(): void
}
enum DecisionStatus {
Proposed
Accepted
Rejected
Deprecated
}
ADR "1" -- "1..*" Comment : has >
ADR "1" -- "1..*" Tag : categorized by >
ADR "1" -- "1" Category : belongs to >
User "1" -- "0..*" Comment : writes >
@enduml
Dieses Diagramm stellt die grundlegenden Klassen und ihre Beziehungen im System zur Verwaltung von ADRs dar. Es umfasst:
Dieses Modell dient als Ausgangspunkt für die weitere Entwicklung und kann je nach Anforderungen angepasst und erweitert werden.
Das Anwendungsfalldiagramm visualisiert die Interaktionen zwischen den Benutzern (Akteuren) und dem System zur Verwaltung von Architecture Decision Records (ADRs). Es dient dazu, die funktionalen Anforderungen aus der Benutzersicht darzustellen.
@startuml
left to right direction
skinparam packageStyle rectangle
actor Entwickler_Architekt as "Entwickler/Architekt"
actor Projektmanager
actor Reviewer
rectangle ADRSystem {
usecase (ADR erstellen) as UC1
usecase (ADR bearbeiten) as UC2
usecase (ADR suchen) as UC3
usecase (ADR anzeigen) as UC4
usecase (ADR kommentieren) as UC5
usecase (ADR bewerten) as UC6
usecase (Benutzer verwalten) as UC7
Entwickler_Architekt --> UC1
Entwickler_Architekt --> UC2
Entwickler_Architekt --> UC3
Entwickler_Architekt --> UC4
Entwickler_Architekt --> UC5
Reviewer --> UC3
Reviewer --> UC4
Reviewer --> UC5
Reviewer --> UC6
Projektmanager --> UC3
Projektmanager --> UC4
Projektmanager --> UC7
}
@enduml
Dieses Diagramm zeigt die Hauptanwendungsfälle des Systems und wie verschiedene Benutzertypen mit diesen interagieren. Es bildet die Grundlage für die weitere detaillierte Spezifikation der Systemfunktionen und -prozesse.
Sequenzdiagramme illustrieren die Interaktionen zwischen Objekten in einer bestimmten Reihenfolge. Sie sind besonders nützlich, um die Dynamik innerhalb des Systems zu verstehen. Im Folgenden werden Sequenzdiagramme für zwei Kernfunktionalitäten des ADR-Verwaltungssystems entwickelt: ADR erstellen und ADR suchen.
Das Sequenzdiagramm für das Erstellen eines ADR zeigt, wie ein Entwickler/Architekt über die Benutzeroberfläche mit dem System interagiert, um einen neuen ADR zu erfassen.
@startuml
participant "UI: Benutzeroberfläche" as UI
participant "Controller" as Controller
participant "ADRService" as Service
database "Datenbank" as DB
UI -> Controller : erstelleADR(anfrage)
Controller -> Service : neuerADR(daten)
Service -> DB : speichereADR(ADR)
DB --> Service : ADRgespeichert
Service --> Controller : Erfolgsmeldung
Controller --> UI : zeigeErfolgsmeldung
@enduml
Das Sequenzdiagramm für das Suchen eines ADR illustriert, wie Benutzer (Entwickler, Projektmanager, Reviewer) eine Suchanfrage stellen und das System die entsprechenden ADRs aus der Datenbank abruft.
@startuml
participant "UI: Benutzeroberfläche" as UI
participant "Controller" as Controller
participant "ADRService" as Service
database "Datenbank" as DB
UI -> Controller : sucheADR(suchkriterien)
Controller -> Service : findeADR(suchkriterien)
Service -> DB : abfrageADR(suchkriterien)
DB --> Service : ADRListe
Service --> Controller : ADRListe
Controller --> UI : zeigeADRListe(ADRListe)
@enduml
Diese Sequenzdiagramme bieten einen detaillierten Einblick in die Prozesse des ADR-Erstellens und Suchens innerhalb des Systems. Sie zeigen die beteiligten Komponenten und die Reihenfolge ihrer Interaktionen, was für das Verständnis des Systemverhaltens und die weitere Implementierung essentiell ist.
Die Definition von Attributen und Methoden für die identifizierten Klassen bildet das Fundament für die Implementierung des Systems zur Verwaltung von Architecture Decision Records (ADRs). Hier folgt eine detaillierte Aufschlüsselung für jede der Hauptklassen.
Attribute: - id: Eindeutige
Identifikationsnummer des ADR. - title: Titel des ADR. -
date: Datum der Erstellung oder Aktualisierung. -
status: Aktueller Status des ADR (z.B. vorgeschlagen,
akzeptiert). - description: Beschreibung der Entscheidung.
- rationale: Begründung für die Entscheidung. -
consequences: Konsequenzen der Entscheidung. -
alternatives: Betrachtete Alternativen.
Methoden: - createADR(): Erstellt einen
neuen ADR-Eintrag. - updateADR(): Aktualisiert einen
bestehenden ADR-Eintrag. - deleteADR(): Löscht einen
ADR-Eintrag.
Attribute: - id: Eindeutige
Identifikationsnummer des Benutzers. - name: Name des
Benutzers. - email: E-Mail-Adresse des Benutzers. -
role: Rolle des Benutzers im System (z.B. Entwickler,
Projektmanager).
Methoden: - createUser(): Fügt einen
neuen Benutzer hinzu. - updateUser(): Aktualisiert
Benutzerinformationen. - deleteUser(): Entfernt einen
Benutzer aus dem System.
Attribute: - id: Eindeutige
Identifikationsnummer der Kategorie. - name: Name der
Kategorie.
Methoden: - createCategory(): Erstellt
eine neue Kategorie. - updateCategory(): Aktualisiert eine
bestehende Kategorie. - deleteCategory(): Löscht eine
Kategorie.
Attribute: - id: Eindeutige
Identifikationsnummer des Tags. - name: Name des Tags.
Methoden: - createTag(): Fügt einen
neuen Tag hinzu. - updateTag(): Aktualisiert einen Tag. -
deleteTag(): Entfernt einen Tag.
Attribute: - id: Eindeutige
Identifikationsnummer des Kommentars. - text: Text des
Kommentars. - date: Datum der Kommentierung. -
userId: Identifikationsnummer des Benutzers, der den
Kommentar erstellt hat.
Methoden: - createComment(): Fügt einen
neuen Kommentar hinzu. - deleteComment(): Löscht einen
Kommentar.
Diese Klassen und ihre Attribute/Methoden bilden die Kernstruktur des Systems zur Verwaltung von ADRs. Die genaue Implementierung dieser Elemente hängt von den spezifischen Anforderungen des Systems sowie den verwendeten Technologien und Frameworks ab.
Für den Entwurf der Klassenstruktur im Rahmen des objektorientierten Designs (OOD) des Systems zur Verwaltung von Architecture Decision Records (ADRs) wird ein Klassendiagramm verwendet, das die Beziehungen zwischen den Hauptklassen zeigt. Dieses Diagramm bildet die Grundlage für die Implementierung des Systems.
@startuml
class ADR {
-id: int
-title: String
-date: Date
-status: DecisionStatus
-description: String
-rationale: String
-consequences: String
-alternatives: String
+createADR(): void
+updateADR(): void
+deleteADR(): void
}
class User {
-id: int
-name: String
-email: String
-role: UserRole
+createUser(): void
+updateUser(): void
+deleteUser(): void
}
class Category {
-id: int
-name: String
+createCategory(): void
+updateCategory(): void
+deleteCategory(): void
}
class Tag {
-id: int
-name: String
+createTag(): void
+updateTag(): void
+deleteTag(): void
}
class Comment {
-id: int
-text: String
-date: Date
-userId: int
+createComment(): void
+deleteComment(): void
}
enum DecisionStatus {
Proposed
Accepted
Rejected
Deprecated
}
enum UserRole {
Developer
ProjectManager
Reviewer
}
ADR "1" -- "1..*" Comment : has >
ADR "1" -- "*" Tag : tagged with >
ADR "1" -- "1" Category : categorized in >
User "1" -- "*" Comment : posts >
@enduml
Dieses Klassendiagramm bietet einen Überblick über die Struktur des Systems und legt die Beziehungen zwischen den verschiedenen Klassen fest. Es ist ein wichtiger Schritt im Designprozess, der die Grundlage für die weitere Entwicklung und Implementierung bildet.
Die erste und zweite Aufgabe des objektorientierten Designs (OOD) – der Entwurf der Klassenstruktur und die Ausarbeitung der Beziehungen und Abhängigkeiten zwischen den Klassen – können effektiv zusammengefasst werden, indem ein umfassendes Klassendiagramm erstellt wird, das sowohl die Struktur als auch die Beziehungen zwischen den Klassen darstellt.
Das folgende PlantUML-Klassendiagramm zeigt die Klassen, ihre Attribute und Methoden, sowie die Beziehungen und Abhängigkeiten zwischen ihnen:
@startuml
' Klassen
class ADR {
-id: int
-title: String
-date: Date
-status: String
-description: String
-rationale: String
-consequences: String
-alternatives: String
+createADR(): void
+updateADR(): void
+deleteADR(): void
}
class User {
-id: int
-name: String
-email: String
-role: String
+createUser(): void
+updateUser(): void
+deleteUser(): void
}
class Category {
-id: int
-name: String
+createCategory(): void
+updateCategory(): void
+deleteCategory(): void
}
class Tag {
-id: int
-name: String
+createTag(): void
+updateTag(): void
+deleteTag(): void
}
class Comment {
-id: int
-text: String
-date: Date
-userId: int
+createComment(): void
+deleteComment(): void
}
' Beziehungen
ADR "0..*" -- "1" User : "erstellt von"
ADR "0..*" -- "0..*" Tag : "hat >"
ADR "0..*" -- "0..1" Category : "gehört zu >"
ADR "0..*" -- "0..*" Comment : "hat >"
Comment "0..*" -- "1" User : "erstellt von"
@enduml
Dieses Klassendiagramm bildet das Gerüst für die Entwicklung und bietet eine klare Sicht auf die Struktur und die Beziehungen innerhalb des Systems zur Verwaltung von Architecture Decision Records. Es hilft Entwicklern, die Implementierung zu planen und sicherzustellen, dass alle Anforderungen abgedeckt sind.
Für die Definition der Schnittstellen zur Interaktion mit externen Systemen und Diensten, insbesondere Datenbanken und Authentifizierungsservices, ist es wichtig, klar definierte Interfaces zu entwerfen. Diese Schnittstellen erleichtern die Integration und Wartung des Systems, indem sie eine Abstraktionsebene zwischen der Geschäftslogik der Anwendung und den externen Diensten bieten.
Das IDataAccess Interface abstrahiert den Zugriff auf
die Datenbank. Es definiert Methoden für CRUD-Operationen (Create, Read,
Update, Delete) für die verschiedenen Entitäten im System.
@startuml
interface IDataAccess {
+createADR(adr: ADR): void
+readADR(id: int): ADR
+updateADR(adr: ADR): void
+deleteADR(id: int): void
+listADRs(criteria: Map<String, Object>): List<ADR>
+createUser(user: User): void
+readUser(id: int): User
+updateUser(user: User): void
+deleteUser(id: int): void
}
@enduml
Das IAuthenticationService Interface definiert Methoden
zur Authentifizierung und Autorisierung von Benutzern. Es ermöglicht das
Einloggen, Ausloggen und Überprüfen von Benutzerberechtigungen.
@startuml
interface IAuthenticationService {
+login(email: String, password: String): User
+logout(user: User): void
+checkPermission(user: User, permission: String): boolean
}
@enduml
Die Implementierung dieser Schnittstellen kann die Nutzung externer
Bibliotheken oder Services umfassen, wie z.B. eine SQL-Datenbank für
IDataAccess oder OAuth2 für
IAuthenticationService. Die konkrete Implementierung hängt
von den technischen Anforderungen und der Systemumgebung ab.
Diese Schnittstellendefinitionen bilden die Grundlage für die Interaktion mit Datenbanken und Authentifizierungsdiensten, zwei wesentliche Aspekte der Systemarchitektur für das ADR-Verwaltungssystem.
Für die detaillierte Beschreibung der Prozesse im Rahmen des objektorientierten Designs werden Aktivitätsdiagramme verwendet. Diese Diagramme illustrieren die Schritte, die in verschiedenen Geschäftsprozessen des Systems durchlaufen werden. Im Folgenden werden zwei Aktivitätsdiagramme für zentrale Prozesse des ADR-Verwaltungssystems erstellt: ADR erstellen und ADR suchen.
Das Aktivitätsdiagramm für den Prozess des Erstellens eines Architecture Decision Records (ADR) zeigt die Schritte vom Beginn bis zum Abschluss des Vorgangs.
@startuml
start
:Benutzer authentifizieren;
if (Authentifizierung erfolgreich?) then (ja)
:Formular anzeigen;
:Eingaben validieren;
if (Daten gültig?) then (ja)
:Neuen ADR speichern;
:Erfolgsmeldung anzeigen;
else (nein)
:Fehlermeldung anzeigen;
endif
else (nein)
:Zugriff verweigern;
endif
stop
@enduml
Das Aktivitätsdiagramm für den Prozess des Suchens eines ADR illustriert, wie Benutzer nach ADRs basierend auf verschiedenen Kriterien suchen können.
@startuml
start
:Suchkriterien eingeben;
:Suchanfrage ausführen;
if (Ergebnisse vorhanden?) then (ja)
:Ergebnisse anzeigen;
else (nein)
:Nachricht "Keine Ergebnisse gefunden" anzeigen;
endif
stop
@enduml
Diese Aktivitätsdiagramme bieten eine visuelle Darstellung der Schritte, die Benutzer und System bei der Durchführung wesentlicher Funktionen des ADR-Verwaltungssystems durchlaufen. Sie helfen Entwicklern und Stakeholdern, die Prozessflüsse zu verstehen und sicherzustellen, dass alle notwendigen Funktionen und Bedingungen im Design berücksichtigt werden.
Um einen OpenAPI Contract zu erstellen, der die Anforderungen zwischen Client und Server für das ADR-Verwaltungssystem abbildet, werden wir uns auf die Kernfunktionalitäten wie das Erstellen, Abrufen, Aktualisieren und Löschen von ADRs konzentrieren. Außerdem werden wir Modelle für ADRs, Benutzer und Kommentare definieren.
openapi: 3.0.0
info:
title: ADR Management System API
description: API for managing Architecture Decision Records (ADRs)
version: 1.0.0
servers:
- url: 'https://api.adrmanagementsystem.com'
paths:
/adrs:
get:
summary: List all ADRs
responses:
'200':
description: A list of ADRs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ADR'
post:
summary: Create a new ADR
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ADR'
responses:
'201':
description: ADR created
/adrs/{id}:
get:
summary: Get a single ADR
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: A single ADR
content:
application/json:
schema:
$ref: '#/components/schemas/ADR'
put:
summary: Update an ADR
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ADR'
responses:
'200':
description: ADR updated
delete:
summary: Delete an ADR
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'204':
description: ADR deleted
components:
schemas:
ADR:
type: object
properties:
id:
type: integer
format: int64
title:
type: string
date:
type: string
format: date
status:
type: string
description:
type: string
rationale:
type: string
consequences:
type: string
alternatives:
type: string
required:
- title
- status
- description
User:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
email:
type: string
required:
- name
- email
Comment:
type: object
properties:
id:
type: integer
format: int64
text:
type: string
date:
type: string
format: date-time
userId:
type: integer
format: int64
required:
- text
- userIdDieser OpenAPI Contract definiert die grundlegenden Endpunkte für die Verwaltung von ADRs, einschließlich Operationen zum Auflisten, Erstellen, Abrufen, Aktualisieren und Löschen von ADRs. Es werden auch die Modelle für ADR, User und Comment mit den erforderlichen Attributen und den Datentypen spezifiziert. Beachten Sie, dass dieser Contract ein Grundgerüst darstellt und je nach spezifischen Anforderungen Ihres Projekts angepasst werden kann.