Skip to content

09_architecture_decisions.adoc

Latest commit

 

History

History
210 lines (152 loc) · 5.89 KB

09_architecture_decisions.adoc

File metadata and controls

210 lines (152 loc) · 5.89 KB

Architekturentscheidungen

Dieses Kapitel referenziert die detaillierten Architecture Decision Records (ADRs) aus dem specs/adrs/ Verzeichnis.

Übersicht der Entscheidungen

ADR Entscheidung Begründung Status

ADR-001

Vite als Static Site Generator

Maximale Flexibilität für Custom-Visualisierung, beste Performance, kein Framework-Lock-in

Accepted

ADR-002

AsciiDoc Attributes für Metadata

Single Source of Truth, einfache Contribution, keine Sync-Probleme

Accepted

ADR-003

Apache ECharts für Treemap

Native Treemap-Unterstützung, exzellente DX, Built-in Theming, Open Source

Superseded by ADR-005

ADR-004

Ein File pro Anchor + Includes

Minimale Merge-Konflikte, klare Git-History, skaliert perfekt

Accepted

ADR-005

Card Grid statt Treemap für Visualisierung

Löst fundamentale Usability-Probleme (Text-Truncation, Kontrast, Viewport), größerer Pugh-Score (+137)

Accepted

ADR-001: Vite als Static Site Generator

Alternative Optionen: Astro, Docusaurus, VitePress, Antora

Pugh-Matrix Ergebnis:

  • Vite: +88 Punkte

  • Astro: 0 (Baseline)

  • Docusaurus: -9

  • VitePress: +11

  • Antora: -69

Kern-Argumente:

  • ✅ Volle Kontrolle über AsciiDoc-Rendering

  • ✅ Maximale Performance durch minimalen Overhead

  • ✅ Keine unnötigen Abstraktionen

  • ❌ Mehr Custom-Code nötig (aber akzeptabel)

Details: ADR-001

ADR-002: AsciiDoc Attributes für Metadata

Alternative Optionen: Separate YAML, Zentrale YAML, Frontmatter, JSON Comment

Pugh-Matrix Ergebnis:

  • AsciiDoc Attributes: +51 Punkte

  • Separate YAML: 0 (Baseline)

  • Zentrale YAML: -30

  • Frontmatter: +25

  • JSON Comment: -41

Kern-Argumente:

  • ✅ Single Source of Truth (1 File pro Anker)

  • ✅ Keine Sync-Probleme zwischen Metadata und Content

  • ✅ AsciiDoc-nativ

  • ❌ AsciiDoc-Parser nötig (aber vorhanden)

Beispiel:

= TDD, London School
:categories: testing-quality
:roles: software-developer, qa-engineer
:related: tdd-chicago-school
:proponents: Steve Freeman, Nat Pryce

Details: ADR-002

ADR-003: Apache ECharts für Treemap

Alternative Optionen: D3.js Custom, Plotly.js, Highcharts, Chart.js

Pugh-Matrix Ergebnis:

  • Apache ECharts: +77 Punkte

  • D3.js: 0 (Baseline)

  • Plotly.js: +48

  • Highcharts: +12

  • Chart.js: +29

Kern-Argumente:

  • ✅ Native Treemap-Unterstützung (keine Custom-Implementation)

  • ✅ Einfache API, schnelle Entwicklung

  • ✅ Built-in Dark/Light Theming

  • ✅ Apache 2.0 Lizenz (kostenlos)

  • ❌ Bundle-Size ~100KB (akzeptabel mit Tree-Shaking)

Code-Beispiel:

const chart = echarts.init(el, 'dark');
chart.setOption({
  series: [{
    type: 'treemap',
    data: categoriesData
  }]
});

Details: ADR-003

ADR-004: Ein File pro Anchor

Alternative Optionen: 1 File/Category, Monolith, Hybrid (komplex), Database

Pugh-Matrix Ergebnis:

  • 1 File/Anchor + Includes: +105 Punkte

  • 1 File/Category: 0 (Baseline)

  • Monolith: -92

  • Hybrid (komplex): +60

  • Database: +38

Kern-Argumente:

  • ✅ Minimale Merge-Konflikte (jeder arbeitet an eigenem File)

  • ✅ Klare Git-History (git log docs/anchors/tdd-london.adoc)

  • ✅ Skaliert perfekt (100, 200, 500 Anker kein Problem)

  • ✅ Flexibles Mapping via AsciiDoc-Includes

  • ❌ Mehr Files (aber gut strukturiert)

Struktur:

docs/
├── anchors/
│   ├── tdd-london-school.adoc    (einzelne Anker)
│   ├── solid-principles.adoc
│   └── ...
├── categories/
│   ├── testing-quality.adoc      (Includes von anchors/)
│   └── ...
└── roles/
    ├── software-developer.adoc   (Includes von anchors/)
    └── ...

Details: ADR-004

ADR-005: Card Grid statt Treemap für Visualisierung

Alternative Optionen: Treemap verbessern (Baseline), Tabs+Liste, Tag Cloud, Table View

Pugh-Matrix Ergebnis:

  • Card Grid: +137 Punkte

  • Treemap verbessern: 0 (Baseline)

  • Table View: +100

  • Tag Cloud: +81

  • Tabs+Liste: +51

Kern-Argumente:

  • ✅ Kein Text-Truncation (voller Platz für Labels)

  • ✅ WCAG-konformer Kontrast (Tailwind colors, kontrollierbar)

  • ✅ Responsive Layout (kein Viewport-Cut-off)

  • ✅ Kleinere Bundle-Size (kein ECharts ~300KB gespart)

  • ✅ Semantic HTML, bessere Accessibility

  • ❌ Mehr vertikaler Platz, Scrolling erforderlich

  • ❌ Weniger visuell beeindruckend als Treemap

Hintergrund: Playwright-Testing zeigte fundamentale Usability-Probleme bei der Treemap: Issue #59 (Text-Truncation), Issue #60 (Map-Cut-off), Issue #61 (Poor Contrast).

Details: ADR-005

Zukünftige Entscheidungen

Offene Punkte:

  • ADR-005: Card Grid Visualisierung - Accepted (ersetzt ADR-003 Treemap)

  • ADR-006: Suchindex-Implementierung (Client-Side vs. Build-Time)

  • ADR-007: Analytics-Lösung (Plausible vs. Simple Analytics vs. Keine)

  • ADR-008: Service Worker für Offline-Support (Ja/Nein)

  • ADR-009: Testing-Framework für E2E (Playwright vs. Cypress)

Entscheidungsprozess

Alle ADRs folgen dem Nygard-Format:

  1. Status: Proposed, Accepted, Deprecated, Superseded

  2. Context: Problemstellung und Anforderungen

  3. Decision: Gewählte Lösung

  4. Consequences: Positive und negative Auswirkungen

Zusätzlich: Pugh-Matrix für objektiven Vergleich von Alternativen.

Template: ADR Template