Monthly Report Kit

Ein reproduzierbares Starterpaket fuer monatliche Kundenreports mit:

• Claude Structured Outputs fuer valide, schemakonforme Inhalte
• fester HTML/CSS-Vorlage statt KI-generiertem Layout
• 28 austauschbaren Designs in 10 Layoutfamilien
• Python/FastAPI-Render-Service
• Gotenberg fuer die PDF-Erzeugung mit Chromium
• JSON-Schema-Validierung vor jedem Rendern
• n8n-Bausteinen und einem importierbaren Beispielworkflow
• Beispielreport, Prompt-Vorlagen und PostgreSQL-Grundstruktur

Architektur

PostgreSQL / andere Datenquelle
        |
        v
n8n normalisiert Monatsdaten
        |
        v
Claude Messages API + output_config.format
        |
        v
validiertes Claude-JSON
        |
        v
Report-Payload aus Kunde + Kennzahlen + Claude-Inhalt
        |
        v
report-renderer -> HTML/Jinja2 -> Gotenberg -> PDF

Claude entscheidet nur, was im Report steht. Das Template entscheidet, wie es aussieht.

Schnellstart

cp .env.example .env
docker compose up -d --build
curl http://localhost:8080/health

Beispielreport erzeugen:

curl \
  --request POST http://localhost:8080/render \
  --header 'Content-Type: application/json' \
  --data @examples/sample-report.json \
  --output output/monatsreport-beispiel.pdf

HTML-Vorschau im Browser:

curl \
  --request POST http://localhost:8080/preview/html \
  --header 'Content-Type: application/json' \
  --data @examples/sample-report.json \
  --output output/preview.html

Wichtigste Dateien

Datei	Zweck
renderer/app/theme_catalog.py	Katalog aller 28 Designs und Farbpaletten
renderer/app/templates/	10 wiederverwendbare Layoutfamilien
scripts/render-theme-gallery.py	erzeugt Vorschauen und einen PDF-Designkatalog
renderer/app/schemas/claude-output-anthropic.schema.json	API-kompatibles Structured-Output-Schema
renderer/app/schemas/claude-output.schema.json	strenge Nachvalidierung mit Textlaengen und Grenzen
renderer/app/schemas/report-payload.schema.json	kompletter Render-Payload
prompts/system-prompt.txt	feste Claude-Rolle und Regeln
prompts/user-prompt-template.txt	dynamischer Auftrag je Kunde/Monat
n8n/workflow-template.json	importierbarer Workflow-Startpunkt
n8n/postgres-schema.sql	Tabellen fuer Konfiguration und Reportlaeufe

Design auswählen

Alle verfügbaren Designs liefert der Renderer über GET /themes. Im Payload genügt die Theme-ID:

{
  "design": {
    "theme": "executive-blue",
    "palette_mode": "theme"
  }
}

palette_mode: "theme" verwendet die fest definierte Farbwelt des Designs. Mit palette_mode: "custom" bleiben Layout und Typografie erhalten, während die im Payload gelieferten Kundenfarben verwendet werden. Die flexiblen Varianten modern und classic verwenden standardmäßig Kundenfarben.

Enthaltene Layoutfamilien

Familie	Charakter	Designs
Modern	Karten, Verlaufskopf, weich	modern, soft-lavender, midnight-gold
Classic	Serifenschrift, feine Linien	classic
Minimal	viel Weißraum, ruhige Flächen	nordic-light, nordic-night, alpine-sage
Dashboard	Management-orientierte KPI-Flächen	executive-blue, executive-charcoal, executive-burgundy
Sidebar	markante Seitenleiste	ocean-breeze, forest-lodge, sunset-coral
Editorial	magazinartige Serifengestaltung	editorial-ivory, editorial-ink, editorial-rose
Magazine	große Typografie, asymmetrische Module	magazine-cobalt, magazine-citrus, magazine-plum
Ledger	dicht, tabellarisch, zahlenorientiert	ledger-green, ledger-blue, ledger-sepia
Split	geteilte Titel- und Inhaltsflächen	split-teal, split-violet, split-terracotta
Poster	plakativ, sehr große Kennzahlen	poster-red, poster-yellow, poster-mono

Den vollständigen visuellen Katalog findest du nach dem Entpacken unter output/theme-catalog/theme-gallery.pdf. Neu erzeugen kannst du ihn mit:

python scripts/render-theme-gallery.py

Produktionshinweise

• API-Key niemals in Workflows exportieren oder im Repository speichern.
• report_version, prompt_version und template_version je Report sichern.
• Vor dem Versand immer Payload- und PDF-Pruefungen ausfuehren.
• Wiederholungen ueber einen eindeutigen Schluessel aus customer_id + period verhindern.
• Externe Bild-URLs vermeiden. Logos als Base64 Data URI uebergeben.

Weitere Hinweise stehen unter docs/.