# Architektur-Dokumentation & Entscheidungen

> Ziel: Jede nicht triviale Lösung ist nachvollziehbar – was, warum, mit welchen Alternativen, und was sie voraussetzt.

## 1. Wann welche Form
| Umfang | Form | Ort |
|---|---|---|
| Einzelne Entscheidung mit Tragweite (Produktwahl, Protokoll, Netzsegmentierung) | **ADR** | `context/knowledge/decisions/adr_NNNN_<slug>.md` |
| Lösung des Projekts | **Architektur-Skizze** (arc42-light, § 2) | `architecture.md` (Root) |
| Dauerhafter Systembestand (Host, Dienst, Netz) | Knowledge-Eintrag | `context/knowledge/{systems,services,network}/` |

## 2. Architektur-Skizze (arc42-light)
1. **Ziel & Rahmen** – Anforderungen, Randbedingungen (Budget, Hardware, Datenschutzklasse).
2. **Kontext** – Diagramm: System, Nutzer, Nachbarsysteme, Schnittstellen (Ports/Protokolle).
3. **Bausteine** – Komponenten, wo sie laufen, wer sie pflegt (Ansible-Rolle, Docker-Stack, Script).
4. **Abläufe** – wichtigste 1–3 Szenarien (z. B. Anmeldung, Backup, Ausfall).
5. **Entscheidungen** – Verweise auf ADRs.
6. **Risiken & offene Punkte**.
7. **Betrieb** – Monitoring, Logging (GELF), Backup/Restore, Update-Weg.

## 3. ADR-Format
Vorlage: [`templates/markdown/adr.md`](templates/markdown/adr.md). Nummern fortlaufend, nie wiederverwenden.
Überholte ADRs nicht löschen: `status: superseded`, `supersedes`/`superseded_by` pflegen.

## 4. Grundsätze für Lösungen im Netz/IT-Umfeld
- **Infrastructure as Code:** Neuaufbau = Playbook/Stack + Secret-Store, nicht Handarbeit. Handgriffe, die bleiben, als `howto/` dokumentieren.
- **Ein Weg pro Aufgabe:** Ansible für Hostkonfiguration, Docker-Compose für Dienste, Bash für Werkzeuge/Glue.
- **Sicher per Default:** minimale Rechte, Default-Ziel ungefährlich, Trockenlauf vor Änderung, Rückfallweg bei Netzänderungen.
- **Beobachtbar:** jeder Dienst mit Healthcheck und zentralem Logging.
- **Wiederherstellbar:** Backup-Pfad und Restore-Test sind Teil der Lösung, nicht Nacharbeit.

## Änderungsprotokoll
- 07.10.2026 – angelegt.
- 23.10.2026 – Architektur-Skizze im Root (Einzelprojekt).