# ADR-001: Multi-Projekt Dokumentations-Architektur

**Status**: Proposed
**Datum**: 2025-10-30
**Entscheider**: Development Team
**Kontext**: Zusammenführung von questra-authentication und questra-data Dokumentationen

## Kontext und Problem

Es existieren mehrere Python-Projekte (questra-authentication, questra-data) mit jeweils eigener MkDocs-Dokumentation. Diese sollen in einer zentralen, einheitlichen Dokumentation zusammengeführt und als nginx Docker Container deployed werden.

### Anforderungen

- Zentrale Dokumentation für alle Questra Python Packages
- Gemeinsames Seven2one Corporate Design (CSS)
- Automatisierte Builds via Azure Pipelines
- Deployment als nginx Docker Container
- Wartbarkeit und Skalierbarkeit für weitere Projekte

## Betrachtete Optionen

1. **Git Submodules** - Dokumentation lebt bei Code
2. **Pipeline Artefakte** - Dokumentation als Build-Artefakte
3. **Monorepo** - Alle Dokumentation in einem Repository

---

## Option 1: Git Submodules

### Beschreibung

Ein zentrales `questra-docs` Repository bindet die Projekt-Repositories als Git Submodules ein. Die Dokumentation bleibt in den jeweiligen Projekt-Repositories bei dem Code.

### Struktur

```
questra-docs/
├── mkdocs.yml                      # Kombinierte Konfiguration
├── docs/
│   ├── index.md                    # Landing Page
│   └── stylesheets/
│       └── extra.css              # Gemeinsames CSS
├── authentication/                 # Git Submodule
│   └── docs/
├── data/                          # Git Submodule
│   └── questra-data/docs/
├── Dockerfile
└── azure-pipelines.yml
```

### Vorgehensweise

```bash
# Setup
git submodule add <auth-repo-url> authentication
git submodule add <data-repo-url> data

# Wartung
git submodule update --remote --merge
```

### Pipeline

```yaml
- checkout: self
  submodules: true
- script: git submodule update --remote
- task: Docker@2
  command: buildAndPush
```

### PRO

✅ **Single Source of Truth**
Dokumentation lebt direkt bei Code - Entwickler sehen/aktualisieren Docs bei Code-Änderungen

✅ **Automatische Versionierung**
Git Submodules tracken exakte Commits - volle Historie verfügbar

✅ **Einfache Wartung**
`git submodule update --remote` holt automatisch neueste Docs

✅ **Keine Pipeline-Dependencies**
Keine Abhängigkeiten von anderen Build-Pipelines nötig

✅ **Developer Experience**
Dokumentation wird bei normalem Development-Workflow aktualisiert

✅ **Lokale Entwicklung einfach**
`git clone --recursive` gibt vollständige Doku-Umgebung

✅ **Skalierbar**
Neue Projekte: `git submodule add <url>` - fertig

### CONTRA

❌ **Submodule-Komplexität**
Team muss Git Submodules verstehen (`git submodule update`)

❌ **Checkout langsamer**
Mehrere Repositories müssen geklont werden

❌ **Pointer auf Commits**
Submodules zeigen auf spezifische Commits, nicht automatisch auf `main`

❌ **Merge-Konflikte möglich**
Bei `.gitmodules` Änderungen können Konflikte entstehen

### Aufwand

- **Initial**: 2-4 Stunden (Setup + Dokumentation)
- **Wartung**: 5-10 Minuten/Monat (Submodule Updates)
- **Neues Projekt**: 15 Minuten

---

## Option 2: Pipeline Artefakte

### Beschreibung

Jedes Projekt baut seine Dokumentation als Artefakt. Das `questra-docs` Repository lädt diese Artefakte herunter und kombiniert sie.

### Struktur

```
questra-docs/
├── mkdocs.yml
├── docs/
│   ├── index.md
│   └── stylesheets/extra.css
├── Dockerfile
└── azure-pipelines.yml            # Lädt Artefakte
```

### Vorgehensweise

Jedes Projekt-Repository:
```yaml
# In authentication/azure-pipelines.yml
- script: mkdocs build
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: 'site'
    ArtifactName: 'auth-docs'
```

Zentrales Repository:
```yaml
# In questra-docs/azure-pipelines.yml
- task: DownloadPipelineArtifact@2
  inputs:
    source: 'specific'
    project: 'Questra'
    pipeline: 'Authentication'
    artifact: 'auth-docs'
    path: 'docs/authentication'
- task: DownloadPipelineArtifact@2
  inputs:
    pipeline: 'Data'
    artifact: 'data-docs'
    path: 'docs/data'
```

### PRO

✅ **Pre-built Dokumentation**
Docs sind bereits gebaut - schnellerer finaler Build

✅ **Unabhängige Builds**
Jedes Projekt kann unabhängig Docs bauen/testen

✅ **Versionskontrolle**
Spezifische Artefakt-Versionen können verwendet werden

✅ **Kein Git Submodules**
Team muss keine Submodules lernen

### CONTRA

❌ **Pipeline-Abhängigkeiten**
`questra-docs` hängt von erfolgreichen Builds anderer Pipelines ab

❌ **Komplexe Pipeline**
Artefakt-Downloads müssen konfiguriert/maintained werden

❌ **Keine lokale Entwicklung**
Ohne Pipeline-Zugriff kann Doku nicht lokal gebaut werden

❌ **Verzögerung**
Änderungen brauchen 2 Pipeline-Runs (Projekt + Docs)

❌ **Artefakt-Verwaltung**
Artefakte müssen retained werden - Storage-Kosten

❌ **Kein Single Source of Truth**
Dokumentation ist verteilt über Artefakt-Stores

❌ **Debugging schwierig**
Bei Problemen: Welches Artefakt ist fehlerhaft?

### Aufwand

- **Initial**: 6-8 Stunden (Pipelines in allen Projekten anpassen)
- **Wartung**: 20-30 Minuten/Monat (Pipeline-Dependencies prüfen)
- **Neues Projekt**: 45 Minuten (neue Pipeline + Download-Task)

---

## Option 3: Monorepo

### Beschreibung

Alle Dokumentation wird aus den Projekt-Repositories in ein zentrales `questra-docs` Repository kopiert/synchronisiert.

### Struktur

```
questra-docs/
├── mkdocs.yml
├── docs/
│   ├── index.md
│   ├── stylesheets/extra.css
│   ├── authentication/            # Kopiert, nicht Submodule
│   │   ├── installation.md
│   │   ├── quickstart.md
│   │   └── api/...
│   └── data/                      # Kopiert, nicht Submodule
│       ├── installation.md
│       └── api/...
├── Dockerfile
└── azure-pipelines.yml
```

### Vorgehensweise

Manuelle Synchronisation:
```bash
# Manuell kopieren
cp -r ../authentication/docs/* docs/authentication/
cp -r ../data/questra-data/docs/* docs/data/
git add .
git commit -m "Update docs"
```

Oder automatisiert via Pipeline:
```yaml
# In project pipelines
- script: |
    git clone https://...questra-docs.git
    cp -r docs/* questra-docs/docs/authentication/
    cd questra-docs
    git add . && git commit -m "Auto-update" && git push
```

### PRO

✅ **Einfachste Struktur**
Alles in einem Repository - keine Submodules/Artefakte

✅ **Schneller Checkout**
Ein einziges `git clone` - sofort lauffähig

✅ **Keine Pipeline-Dependencies**
Unabhängig von anderen Projekten

✅ **Einfaches Debugging**
Alle Dateien direkt sichtbar und editierbar

✅ **Volle Kontrolle**
Doku kann unabhängig von Code-Releases aktualisiert werden

### CONTRA

❌ **Kein Single Source of Truth**
Dokumentation ist dupliziert - Sync-Probleme vorprogrammiert

❌ **Manuelle Synchronisation**
Änderungen müssen explizit kopiert werden

❌ **Veraltete Dokumentation**
Ohne Automatisierung schnell out-of-sync

❌ **Duplicate Content**
Dokumentation existiert 2x - Speicher-Overhead

❌ **Merge-Konflikte häufig**
Bei parallelen Änderungen in mehreren Projekten

❌ **Fehleranfällig**
Vergessene Updates führen zu inkonsistenter Doku

❌ **Code-Doku Disconnect**
Developer sehen Doku-Änderungen nicht bei Code-Änderungen

### Aufwand

- **Initial**: 3-5 Stunden (Einmal kopieren + Automation)
- **Wartung**: 30-60 Minuten/Monat (Synchronisation prüfen/durchführen)
- **Neues Projekt**: 30 Minuten (Kopieren + Automation erweitern)

---

## Entscheidungsmatrix

| Kriterium | Git Submodules | Pipeline Artefakte | Monorepo |
|-----------|----------------|-------------------|----------|
| **Single Source of Truth** | ✅ Excellent | ❌ Poor | ❌ Poor |
| **Developer Experience** | ✅ Excellent | ❌ Poor | ⚠️ Medium |
| **Wartbarkeit** | ✅ Excellent | ❌ Poor | ⚠️ Medium |
| **Setup-Komplexität** | ⚠️ Medium | ❌ High | ✅ Low |
| **Pipeline-Komplexität** | ✅ Low | ❌ High | ✅ Low |
| **Lokale Entwicklung** | ✅ Excellent | ❌ Poor | ✅ Excellent |
| **Skalierbarkeit** | ✅ Excellent | ⚠️ Medium | ❌ Poor |
| **Automatisierung** | ✅ Excellent | ✅ Excellent | ⚠️ Medium |
| **Fehleranfälligkeit** | ⚠️ Medium | ❌ High | ❌ High |
| **Initiale Kosten** | ⚠️ 2-4h | ❌ 6-8h | ✅ 3-5h |
| **Laufende Kosten** | ✅ 5-10min | ❌ 20-30min | ⚠️ 30-60min |

**Legende**: ✅ Gut | ⚠️ Akzeptabel | ❌ Problematisch

---

## Detaillierter Vergleich

### Single Source of Truth

**Git Submodules**: ✅
Dokumentation lebt bei Code. Entwickler aktualisieren Docs im gleichen PR wie Code-Änderungen.

**Pipeline Artefakte**: ❌
Dokumentation ist in Artefakt-Store verstreut. Schwer nachvollziehbar, welche Version aktuell ist.

**Monorepo**: ❌
Dokumentation existiert dupliziert. Synchronisation manuell oder via Script - fehleranfällig.

### Developer Experience

**Git Submodules**: ✅
Developer arbeitet normal im Projekt-Repo. Docs automatisch bei Code-Änderungen aktualisiert.

**Pipeline Artefakte**: ❌
Developer sieht kombinierte Doku nur nach Pipeline-Run. Kein lokales Testing möglich.

**Monorepo**: ⚠️
Developer muss in zwei Repos arbeiten oder Sync-Script verwenden. Erhöhter Aufwand.

### Wartbarkeit

**Git Submodules**: ✅
`git submodule update --remote` - fertig. Automatisierbar in Pipeline.

**Pipeline Artefakte**: ❌
Jede neue Pipeline muss konfiguriert werden. Download-Tasks müssen gewartet werden.

**Monorepo**: ⚠️
Sync-Script muss funktionieren. Bei Problemen: manuelle Intervention nötig.

### Setup-Komplexität

**Git Submodules**: ⚠️
Team muss Git Submodules verstehen. Initiales Setup mit Dokumentation machbar.

**Pipeline Artefakte**: ❌
Komplexe Pipeline-Konfiguration in allen Projekten. Viele Moving Parts.

**Monorepo**: ✅
Einfachste Struktur. Jeder versteht sofort, wie es funktioniert.

### Skalierbarkeit

**Git Submodules**: ✅
Neues Projekt: `git submodule add` + Navigation in mkdocs.yml. 15 Minuten.

**Pipeline Artefakte**: ⚠️
Neues Projekt: Pipeline anpassen + Download-Task + Artefakt-Namen. 45 Minuten.

**Monorepo**: ❌
Neues Projekt: Sync-Script erweitern + manuelle Kopier-Strategie. Skaliert schlecht.

---

## Empfehlung

### **Option 1: Git Submodules** ✅

**Begründung**:

1. **Best Practice für Multi-Repo Dokumentation**
   Git Submodules ist der Standard-Ansatz für diese Problemstellung

2. **Single Source of Truth**
   Dokumentation lebt bei Code - verhindert Inkonsistenzen

3. **Developer Workflow**
   Minimaler Overhead für Entwickler - Docs im normalen Workflow

4. **Wartbarkeit**
   Niedrigste laufende Kosten (5-10 min/Monat)

5. **Skalierbarkeit**
   Weitere Projekte einfach hinzufügbar

6. **Bewährte Technologie**
   Git Submodules ist etabliert und gut dokumentiert

### Implementierungsstrategie

1. **Phase 1** (Tag 1-2): Repository Setup
   - `questra-docs` Repository erstellen
   - Submodules hinzufügen
   - mkdocs.yml konfigurieren

2. **Phase 2** (Tag 3): Docker & Pipeline
   - Dockerfile erstellen
   - nginx konfigurieren
   - Azure Pipeline einrichten

3. **Phase 3** (Tag 4): Testing & Deployment
   - Lokale Tests
   - Docker Build testen
   - Production Deployment

4. **Phase 4** (Woche 2): Team Onboarding
   - Dokumentation für Team
   - Submodule-Workflow erklären
   - Best Practices etablieren

### Risiken & Mitigation

**Risiko**: Team kennt Git Submodules nicht
**Mitigation**: Dokumentation + kurzes Training (30 min)

**Risiko**: Submodules zeigen auf alte Commits
**Mitigation**: Automatisches `git submodule update --remote` in Pipeline

**Risiko**: Checkout dauert länger
**Mitigation**: Akzeptabel für bessere Wartbarkeit (Trade-off)

---

## Alternativen bei späteren Problemen

Falls Git Submodules nicht funktioniert:

1. **Monorepo** (einfacher Fallback)
   Wenn Team absolut keine Submodules möchte

2. **Pipeline Artefakte** (bei sehr großen Repos)
   Wenn Checkout-Zeit kritisch wird

---

## Konsequenzen

### Positiv

- ✅ Dokumentation immer aktuell mit Code
- ✅ Developer Experience verbessert
- ✅ Wartungsaufwand minimiert
- ✅ Skalierbar für weitere Projekte

### Negativ

- ⚠️ Team muss Git Submodules lernen (einmalig)
- ⚠️ Checkout dauert etwas länger
- ⚠️ Initiales Setup aufwändiger als Monorepo

### Neutral

- Existing Projekt-Repositories bleiben unverändert
- CSS wird zentral verwaltet (Migration nötig)

---

## Referenzen

- [Git Submodules Documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
- [MkDocs Multi-Repo Setup](https://www.mkdocs.org/user-guide/configuration/)
- MULTI_PROJECT_DOCS.md - Detaillierte Implementierungsanleitung

---

## Nächste Schritte

1. [ ] Entscheidung durch Team Review
2. [ ] `questra-docs` Repository in Azure DevOps erstellen
3. [ ] Implementierung nach MULTI_PROJECT_DOCS.md
4. [ ] Team Onboarding Session planen
5. [ ] Production Deployment

---

**Notizen**:
- ADR kann bei Problemen revidiert werden
- Nach 6 Monaten: Review der Entscheidung
- Feedback vom Team einholen nach Implementierung
