Einsatzbereit - Architekturdokumentation

Danksagung

Diese Architekturdokumentation basiert auf arc42 - einem großartigen, frei verfügbaren Template zur Dokumentation von Software- und Systemarchitekturen.

Erstellt, verwaltet und © von Dr. Peter Hruschka, Dr. Gernot Starke und Mitwirkenden.

1. Einführung und Ziele

Einsatzbereit ist eine Open-Source Plattform, die engagierte Helfer:innen mit regionalen Bedarfen zusammenbringt. Das Ehrenamt und der konkrete Nutzen für die Gesellschaft stehen dabei immer im Vordergrund.

Die Plattform verfolgt drei Leitprinzipien:

Ehrenamt zuerst: Jede Entscheidung, ob Feature, Architektur oder Prozess, dient dem Ziel, ehrenamtliches Engagement zu erleichtern.
Einfacher Code: Der Quellcode soll so simpel sein, dass jede und jeder mitarbeiten kann, auch ohne tiefe Vorkenntnisse.
Kein Ballast: Die Plattform zu pflegen soll keine Last sein, sondern sie soll ein leichtgewichtiger Helfer bleiben.

1.1. Aufgabenstellung

Wer helfen will, muss sich nicht langfristig binden. Manchmal passt ein Nachmittag, manchmal eine Woche. Aber einen Überblick zu bekommen, wo gerade Hilfe gebraucht wird, ist oft schwer - egal ob bei großen NGOs oder beim Sportturnier um die Ecke. Bestehende Plattformen sind häufig zu kompliziert, zu allgemein oder werden kaum genutzt.

Einsatzbereit löst dieses Problem, indem es konkrete Bedarfe sichtbar macht: was wird gebraucht, wo und wann.

Wesentliche funktionale Anforderungen:

Organisationen und Vereine können Hilfsbedarfe mit Ort, Zeitraum und benötigten Fähigkeiten eintragen.
Helfer:innen können nach passenden Einsätzen in ihrer Region suchen und sich melden.
Die Nutzung ist ohne langfristige Verpflichtung möglich.

Tabelle 1. Geschäftsziele
Ziel	Beschreibung
Ehrenamt stärken	Freiwilliges Engagement sichtbar und zugänglich machen - ohne bürokratische Hürden oder langfristige Bindung.
Offen und nachhaltig	Das Projekt ist unter der GNU AGPL v3.0 lizenziert. Kein Profit, kein Closed Source, kein verlorenes Wissen. Es ist zweitrangig, wer das Projekt weiterentwickelt - der Nutzen soll im Vordergrund stehen.
Niedrige Einstiegshürde	Sowohl für Nutzende als auch für Contributor soll der Einstieg so einfach wie möglich sein.

1.2. Qualitätsziele

Die folgenden Qualitätsziele definieren die wesentlichen Qualitätsanforderungen an Einsatzbereit und dienen als Leitfaden für architektonische Entscheidungen.

Tabelle 2. Primäre Qualitätsziele
Qualitätsmerkmal	Beschreibung	Gewichtung
Zweckmäßigkeit	Jede Funktion dient direkt dem Ehrenamt. Kein Feature-Bloat, kein Overengineering - nur das, was den Nutzen für Helfer:innen oder Organisationen konkret steigert.	Sehr hoch
Einfachheit	Code und Architektur sind so gestaltet, dass neue Contributor sie ohne tiefes Vorwissen verstehen können. Neue Funktionen lassen sich umsetzen, ohne das Gesamtsystem verstehen zu müssen. Einfachheit hat Vorrang vor Flexibilität.	Hoch
Wartbarkeit	Die Plattform kann mit minimalem Aufwand betrieben und weiterentwickelt werden. Abhängigkeiten und Build-Prozesse funktionieren mit Standardwerkzeugen. Pflege soll keine Last sein, sondern selbstverständlich.	Hoch
Benutzbarkeit	Die Plattform ist intuitiv bedienbar. Helfer:innen und Organisationen können ihre Aufgaben ohne Einarbeitung oder technisches Vorwissen erledigen.	Hoch

Eine vollständige Liste aller Qualitätsziele mit detaillierten Szenarien findet sich in Kapitel 10 Qualitätsanforderungen.

1.3. Stakeholder

Rolle	Kontakt	Erwartungshaltung
Ehrenamtliche Helfer:innen	Endnutzer:innen	„Ich hab Samstagnachmittag frei und will was Sinnvolles tun, aber bitte ohne mich erst durch drei Formulare zu kämpfen." Helferin Hannah erwartet eine intuitive Oberfläche, über die sie schnell passende Einsätze findet, ohne Registrierungshürden oder Verpflichtung.
Organisationen und Vereine	Endnutzer:innen	„Wir brauchen am Wochenende zehn Leute für den Aufbau. Ich will das in fünf Minuten eingetragen haben, nicht in fünfzig." Organisator Olaf erwartet einen einfachen Weg, Hilfsbedarfe einzutragen und Helfer:innen zu erreichen, ohne technisches Vorwissen.
Contributor	GitHub Issues und Pull Requests	„Ich will an einem Wochenende ein Feature beisteuern, nicht erst zwei Tage das Projekt verstehen müssen." Contributerin Caro erwartet simplen, gut strukturierten Code, klare Contribution-Guidelines und Dokumentation, die den Einstieg erleichtert.
Maintainer	GitHub Repository	„Je weniger ich nachts um zwei fixen muss, desto besser. Einfach halten, automatisieren, fertig." Maintainer Milo erwartet geringen Pflegeaufwand durch einfache Architektur, automatisierte CI/CD-Pipelines und wenige externe Abhängigkeiten.

Rolle

Kontakt

Erwartungshaltung

Ehrenamtliche Helfer:innen

Endnutzer:innen

„Ich hab Samstagnachmittag frei und will was Sinnvolles tun, aber bitte ohne mich erst durch drei Formulare zu kämpfen."

Helferin Hannah erwartet eine intuitive Oberfläche, über die sie schnell passende Einsätze findet, ohne Registrierungshürden oder Verpflichtung.

Organisationen und Vereine

Endnutzer:innen

„Wir brauchen am Wochenende zehn Leute für den Aufbau. Ich will das in fünf Minuten eingetragen haben, nicht in fünfzig."

Organisator Olaf erwartet einen einfachen Weg, Hilfsbedarfe einzutragen und Helfer:innen zu erreichen, ohne technisches Vorwissen.

Contributor

GitHub Issues und Pull Requests

„Ich will an einem Wochenende ein Feature beisteuern, nicht erst zwei Tage das Projekt verstehen müssen."

Contributerin Caro erwartet simplen, gut strukturierten Code, klare Contribution-Guidelines und Dokumentation, die den Einstieg erleichtert.

Maintainer

GitHub Repository

„Je weniger ich nachts um zwei fixen muss, desto besser. Einfach halten, automatisieren, fertig."

Maintainer Milo erwartet geringen Pflegeaufwand durch einfache Architektur, automatisierte CI/CD-Pipelines und wenige externe Abhängigkeiten.

2. Randbedingungen

3. Kontextabgrenzung

3.1. Fachlicher Kontext

Abbildung 1. Fachliche Kontextsicht

Tabelle 3. Beschreibung der Elemente
Element	Beschreibung
Helferin Hannah	Sucht nach Möglichkeiten regional ehrenamtilich tätig zu werden
Organisator Olaf	Erstellt Bedürfnisse für sein derzeitiges Event / sucht nach ehrentamtlicher Untersützung
Einsatzbereit	Ermöglicht das Verwalten von regionalen Bedürfnissen und dem Anmelden helfen zu wollen

3.2. Technischer Kontext

<Diagramm oder Tabelle>

<optional: Erläuterung der externen technischen Schnittstellen>

<Mapping fachliche auf technische Schnittstellen>

4. Lösungsstrategie

5. Bausteinsicht

5.1. Whitebox Gesamtsystem

<Übersichtsdiagramm>

Begründung: <Erläuternder Text>
Enthaltene Bausteine: <Beschreibung der enthaltenen Bausteine (Blackboxen)>
Wichtige Schnittstellen: <Beschreibung wichtiger Schnittstellen>

5.1.1. <Name Blackbox 1>

<Zweck/Verantwortung>

<Schnittstelle(n)>

<(Optional) Qualitäts-/Leistungsmerkmale>

<(Optional) Ablageort/Datei(en)>

<(Optional) Erfüllte Anforderungen>

<(optional) Offene Punkte/Probleme/Risiken>

5.1.2. <Name Blackbox 2>

<Blackbox-Template>

5.1.3. <Name Blackbox n>

<Blackbox-Template>

5.1.4. <Name Schnittstelle 1>

…

5.1.5. <Name Schnittstelle m>

5.2. Ebene 2

5.2.1. Whitebox <Baustein 1>

<Whitebox-Template>

5.2.2. Whitebox <Baustein 2>

<Whitebox-Template>

…

5.2.3. Whitebox <Baustein m>

<Whitebox-Template>

5.3. Ebene 3

5.3.1. Whitebox <_Baustein x.1_>

<Whitebox-Template>

5.3.2. Whitebox <_Baustein x.2_>

<Whitebox-Template>

5.3.3. Whitebox <_Baustein y.1_>

<Whitebox-Template>

6. Laufzeitsicht

6.1. <Bezeichnung Laufzeitszenario 1>

<hier Laufzeitdiagramm oder Ablaufbeschreibung einfügen>
<hier Besonderheiten bei dem Zusammenspiel der Bausteine in diesem Szenario erläutern>

6.2. <Bezeichnung Laufzeitszenario 2>

…

6.3. <Bezeichnung Laufzeitszenario n>

…

7. Verteilungssicht

7.1. Infrastruktur Ebene 1

<Übersichtsdiagramm>

Begründung: <Erläuternder Text>
Qualitäts- und/oder Leistungsmerkmale: <Erläuternder Text>
Zuordnung von Bausteinen zu Infrastruktur: <Beschreibung der Zuordnung>

7.2. Infrastruktur Ebene 2

7.2.1. <Infrastrukturelement 1>

<Diagramm + Erläuterungen>

7.2.2. <Infrastrukturelement 2>

<Diagramm + Erläuterungen>

…

7.2.3. <Infrastrukturelement n>

<Diagramm + Erläuterungen>

8. Querschnittliche Konzepte

8.1. <Konzept 1>

<Erklärung>

8.2. <Konzept 2>

<Erklärung>

…

8.3. <Konzept n>

<Erklärung>

9. Architekturentscheidungen

In folgender Tabelle werden die relevanten Architekturentscheidungen aufgelistet.

Tabelle 4. Architekturentscheidungen
Nr.	Kontext	Beschreibung	Status	Datum	ADR
1	Monorepository	Alle Komponenten in einem Repository verwalten.	Akzeptiert	23.03.2026	Monorepository
2	arc42	arc42 als Vorlage für die Architekturdokumentation verwenden.	Akzeptiert	25.03.2026	arc42
3	Keycloak	Keycloak als Identity- und Access-Management-Lösung einsetzen.	Akzeptiert	25.03.2026	Keycloak

10. Qualitätsanforderungen

10.1. Qualitätsziele im Überblick

Die folgende Tabelle gibt einen Überblick über alle Qualitätsziele des Systems, sortiert nach ihrer Gewichtung. Die Ziele und Szenarien dienen als Leitfaden für architektonische Entscheidungen.

Tabelle 5. Vollständige Liste der Qualitätsziele
Qualitätsmerkmal	Beschreibung	Gewichtung
Zweckmäßigkeit	Jede Funktion dient direkt dem Ehrenamt. Kein Feature-Bloat, kein Overengineering - nur das, was den Nutzen für Helfer:innen oder Organisationen konkret steigert.	Sehr hoch
Einfachheit	Code und Architektur sind so gestaltet, dass neue Contributor sie ohne tiefes Vorwissen verstehen können. Neue Funktionen lassen sich umsetzen, ohne das Gesamtsystem verstehen zu müssen. Einfachheit hat Vorrang vor Flexibilität.	Hoch
Wartbarkeit	Die Plattform kann mit minimalem Aufwand betrieben und weiterentwickelt werden. Abhängigkeiten und Build-Prozesse funktionieren mit Standardwerkzeugen. Pflege soll keine Last sein, sondern selbstverständlich.	Hoch
Benutzbarkeit	Die Plattform ist intuitiv bedienbar. Helfer:innen und Organisationen können ihre Aufgaben ohne Einarbeitung oder technisches Vorwissen erledigen.	Hoch

10.2. Qualitätsbaum

Abbildung 2. Qualitätsbaum

10.3. Qualitätsszenarien

10.3.1. Zweckmäßigkeit

ID	Szenario	Erläuterung
QS-1.1	Ein neues Feature wird vorgeschlagen.	Vor der Umsetzung wird geprüft, ob es den Nutzen für Helfer:innen oder Organisationen konkret steigert. Features ohne klaren Bezug zum Ehrenamt werden abgelehnt.
QS-1.2	Die Architektur soll um eine neue Abstraktionsebene erweitert werden.	Die Erweiterung wird nur umgesetzt, wenn sie einen konkreten, aktuellen Bedarf adressiert - nicht für hypothetische zukünftige Anforderungen.

Szenario

Erläuterung

QS-1.1

Ein neues Feature wird vorgeschlagen.

Vor der Umsetzung wird geprüft, ob es den Nutzen für Helfer:innen oder Organisationen konkret steigert. Features ohne klaren Bezug zum Ehrenamt werden abgelehnt.

QS-1.2

Die Architektur soll um eine neue Abstraktionsebene erweitert werden.

Die Erweiterung wird nur umgesetzt, wenn sie einen konkreten, aktuellen Bedarf adressiert - nicht für hypothetische zukünftige Anforderungen.

10.3.2. Einfachheit

ID	Szenario	Erläuterung
QS-2.1	Ein neuer Contributor möchte zum ersten Mal Code beitragen.	Die Person kann den Code ohne tiefes Vorwissen verstehen und innerhalb eines Tages einen ersten Beitrag leisten. Die CONTRIBUTING.md und die Projektstruktur sind selbsterklärend.
QS-2.2	Eine neue Funktion soll implementiert werden.	Die Änderung lässt sich umsetzen, ohne das Gesamtsystem verstehen zu müssen. Die betroffene Komponente ist klar abgegrenzt.
QS-2.3	Ein Contributor liest zum ersten Mal den Quellcode einer Komponente.	Durch flache Hierarchien, wenige Abstraktionsebenen und klare Benennung ist der Code ohne zusätzliche Dokumentation verständlich.

Szenario

Erläuterung

QS-2.1

Ein neuer Contributor möchte zum ersten Mal Code beitragen.

Die Person kann den Code ohne tiefes Vorwissen verstehen und innerhalb eines Tages einen ersten Beitrag leisten. Die CONTRIBUTING.md und die Projektstruktur sind selbsterklärend.

QS-2.2

Eine neue Funktion soll implementiert werden.

Die Änderung lässt sich umsetzen, ohne das Gesamtsystem verstehen zu müssen. Die betroffene Komponente ist klar abgegrenzt.

QS-2.3

Ein Contributor liest zum ersten Mal den Quellcode einer Komponente.

Durch flache Hierarchien, wenige Abstraktionsebenen und klare Benennung ist der Code ohne zusätzliche Dokumentation verständlich.

10.3.3. Wartbarkeit

ID	Szenario	Erläuterung
QS-3.1	Ein Versionsupdate einer Abhängigkeit steht an.	Durch zentrales Dependency-Management (Directory.Packages.props) muss die Version nur an einer Stelle geändert werden.
QS-3.2	Ein CI-Build schlägt fehl.	Die Fehlermeldung ist klar und ohne Kontextwissen nachvollziehbar. Die Ursache lässt sich schnell eingrenzen.
QS-3.3	Eine neue Person übernimmt die Pflege des Projekts.	Durch Standardwerkzeuge, automatisierte Pipelines und die Monorepository-Struktur ist der Einstieg in die Wartung ohne aufwendige Einarbeitung möglich.

Szenario

Erläuterung

QS-3.1

Ein Versionsupdate einer Abhängigkeit steht an.

Durch zentrales Dependency-Management (Directory.Packages.props) muss die Version nur an einer Stelle geändert werden.

QS-3.2

Ein CI-Build schlägt fehl.

Die Fehlermeldung ist klar und ohne Kontextwissen nachvollziehbar. Die Ursache lässt sich schnell eingrenzen.

QS-3.3

Eine neue Person übernimmt die Pflege des Projekts.

Durch Standardwerkzeuge, automatisierte Pipelines und die Monorepository-Struktur ist der Einstieg in die Wartung ohne aufwendige Einarbeitung möglich.

10.3.4. Benutzbarkeit

ID	Szenario	Erläuterung
QS-4.1	Eine Organisation möchte zum ersten Mal einen Hilfsbedarf eintragen.	Der Vorgang ist ohne Schulung oder Handbuch möglich und innerhalb weniger Minuten abgeschlossen.
QS-4.2	Eine helfende Person sucht nach Einsätzen in ihrer Nähe.	Die Suche liefert relevante Ergebnisse mit klarer Darstellung von Was, Wo und Wann - ohne überladene Oberfläche.

Szenario

Erläuterung

QS-4.1

Eine Organisation möchte zum ersten Mal einen Hilfsbedarf eintragen.

Der Vorgang ist ohne Schulung oder Handbuch möglich und innerhalb weniger Minuten abgeschlossen.

QS-4.2

Eine helfende Person sucht nach Einsätzen in ihrer Nähe.

Die Suche liefert relevante Ergebnisse mit klarer Darstellung von Was, Wo und Wann - ohne überladene Oberfläche.

11. Risiken und technische Schulden

12. Glossar

Begriff	Definition
<Begriff-1>	<Definition-1>
<Begriff-2	<Definition-2>

Begriff

Definition

<Begriff-1>

<Definition-1>

<Begriff-2

<Definition-2>