docs(ui): condense and translate email, UI and PDF docs to English

This commit is contained in:
Moritz 2026-06-15 21:53:36 +02:00
parent 0b36a43edc
commit 3797bc8fae
5 changed files with 113 additions and 731 deletions

View file

@ -1,71 +1,32 @@
# PDF Generation: Imprintor statt Chromium
# PDF Generation: Imprintor instead of Chromium
## Übersicht
## Decision
Für die PDF-Generierung in der Mitgliederverwaltung verwenden wir **Imprintor** (`~> 0.5.0`) anstelle von Chromium-basierten Lösungen (wie z.B. Puppeteer, Chrome Headless, oder ähnliche).
For PDF generation we use **Imprintor** (`{:imprintor, "~> 0.6.0"}`) with
**Typst** templates, rather than a Chromium-based renderer (Puppeteer, Chrome
Headless, etc.). Implemented in `lib/mv/membership/members_pdf.ex`, template at
`priv/pdf_templates/members_export.typ`.
## Warum Imprintor statt Chromium?
## Rationale (Imprintor over Chromium)
### 1. Ressourceneffizienz
- **Resource efficiency:** no full browser instance in memory, no
browser-rendering pipeline on the CPU.
- **Smaller Docker images:** no Chromium install (saves several hundred MB);
works in minimal images (e.g. Alpine), with no system dependencies
(Chromium, ChromeDriver) to ship or keep updated.
- **Elixir-native:** integrates with the BEAM and Elixir error handling instead
of managing an external browser process; faster generation and easier
parallelism (no browser startup or instance management).
- **Smaller attack surface:** no browser engine with its own CVE stream.
- **Geringerer Speicherverbrauch**: Imprintor benötigt keine vollständige Browser-Instanz im Speicher
- **Niedrigere CPU-Last**: Native PDF-Generierung ohne Browser-Rendering-Pipeline
- **Kleinere Docker-Images**: Keine Chromium-Installation erforderlich (spart mehrere hundert MB)
## When Chromium would still be warranted
### 2. Performance
- **Schnellere Generierung**: Direkte PDF-Generierung ohne HTML-Rendering-Overhead
- **Bessere Skalierbarkeit**: Kann mehrere PDFs parallel generieren ohne Browser-Instanzen zu verwalten
- **Niedrigere Latenz**: Keine Browser-Startup-Zeit
### 3. Deployment & Wartung
- **Einfacheres Deployment**: Keine System-Abhängigkeiten (Chromium, ChromeDriver, etc.)
- **Weniger Wartungsaufwand**: Keine Browser-Version-Updates zu verwalten
- **Bessere Container-Kompatibilität**: Funktioniert in minimalen Docker-Images (z.B. Alpine)
### 4. Sicherheit
- **Kleinere Angriffsfläche**: Keine Browser-Engine mit bekannten Sicherheitslücken
- **Isolation**: Weniger System-Calls und externe Prozesse
### 5. Elixir-Native Lösung
- **Erlang/OTP-Integration**: Nutzt die Vorteile der BEAM-VM (Concurrency, Fault Tolerance)
- **Type-Safety**: Bessere Integration mit Elixir-Typen und Pattern Matching
- **Einfachere Fehlerbehandlung**: Elixir-native Error-Handling statt externer Prozesse
## Wann Chromium trotzdem sinnvoll wäre
Chromium-basierte Lösungen sind sinnvoll, wenn:
- Komplexe JavaScript-Ausführung im HTML nötig ist
- Moderne CSS-Features (Grid, Flexbox, etc.) kritisch sind
- Screenshots von Web-Seiten generiert werden sollen
- Dynamische Inhalte gerendert werden müssen, die JavaScript erfordern
## Verwendung in diesem Projekt
Imprintor wird für folgende Anwendungsfälle verwendet:
- **Member-Export als PDF**: Generierung von Mitgliederlisten und -reports
- **Statische Reports**: PDF-Generierung für vordefinierte Report-Formate
- **Dokumente**: Generierung von Mitgliedschaftsbescheinigungen, Rechnungen, etc.
## Technische Details
- **Dependency**: `{:imprintor, "~> 0.5.0"}`
- **Typ**: Native Elixir-Bibliothek (vermutlich basierend auf Rust-NIFs oder ähnlichen Technologien)
- **Format**: Generiert PDF direkt aus HTML/Templates ohne Browser-Engine
## Migration von Chromium (falls vorhanden)
Falls zuvor eine Chromium-basierte Lösung verwendet wurde:
1. HTML-Templates müssen ggf. angepasst werden (kein JavaScript-Support)
2. CSS muss statisch sein (keine dynamischen Styles)
3. Komplexe Layouts sollten vorher getestet werden
## Weitere Ressourcen
- [Imprintor auf Hex.pm](https://hex.pm/packages/imprintor)
- [GitHub Repository](https://github.com/[imprintor-repo]) (falls verfügbar)
A Chromium-based renderer makes sense when the document requires JavaScript
execution, dynamic JS-rendered content, modern web CSS features, or full-page
screenshots of web pages — none of which apply to our static, template-driven
exports.
## Usage in this project
Member export as PDF (member lists / reports) and other static, predefined
documents (e.g. membership certificates).