Agentic Ventures Wiki

Woehrle Stack — Zettle + Lexware Office XL + OWUI auf Hetzner (Implementierungsplan)

20 Min. Lesezeit

Implementierungs-Plan Woehrle Stack

Overview

Komplett-Stack fuer Weinhandel + Weingalerie auf Hetzner: Zettle (Kasse + TSE + Inventar) + Lexware Office XL (Buchhaltung, API) + Open WebUI (KI-Chat-Layer ueber MCPs) + ggf. Ticketsystem fuer Weingalerie-Events. Endkundenpreis 200 EUR/Monat brutto, ~143 EUR Marge.

Zwei Investments mit Compounding-Effekt fuer naechste Kunden:

  1. mcp-zettle neu bauen (Standard-Stack-Layer fuer alle naechsten Retail/Gastro-Kunden mit Zettle)
  2. mcp-lexware-office von read-only auf full-CRUD ausbauen (Standard-Stack-Layer fuer alle KMU mit lexoffice)

Problem Frame

Woehrle ist Weinhaendler mit Weingalerie als Event-Location (Weinproben, gelegentliche Veranstaltungen). Aktueller Zustand: kein digitales Buchhaltungs-Tool, vermutlich Excel/Papier-Kasse, kein TSE-konformes System. KassenSichV § 146a AO macht TSE pflichtig — also ohnehin Zwangsmodernisierung. Plus Wunsch nach KI-Chat-Bedienung als Differenzierung („AI-Workplace fuer Kleinunternehmen”-Storyline).

Gesamtsicht: Ein KMU-Stack-Bundle das wir produktisiert anbieten — fuer Woehrle einmalig hand-gebaut, ab Kunde 2 wiederverwendbar.

Requirements Trace

  • R1 TSE-konforme Kasse, KassenSichV ab Tag 1.
  • R2 GoBD-konforme Buchhaltung mit DATEV-Export fuer Steuerberater.
  • R3 REST-API fuer OWUI-Layer auf beiden Datenquellen (Kasse + Buchhaltung).
  • R4 Lagerverwaltung im Kasse-System (Wein-SKUs, Bestand, Mehrwertsteuer-Splits 7%/19%).
  • R5 Ticketsystem fuer Weingalerie-Events — Format wird im Discovery festgelegt (Online-Vorverkauf oder Tageskasse).
  • R6 KI-Chat-Layer ueber OWUI fuer ~5 konkrete Use-Cases (Tagesumsatz, Bestseller, Lagerstand, Event-Anmeldung, Kundennachricht).
  • R7 Hosting komplett auf Hetzner (per Kundenwunsch).
  • R8 200 EUR/Monat brutto Endkundenpreis nach Setup-Phase. Externe Kosten ~57 EUR, Marge ~143 EUR.
  • R9 Self-Service-Setup fuer alle SaaS-Komponenten (Zettle, Lexware Office) — kein Vertriebs-Funnel.

Scope Boundaries

Nicht-Ziele:

  • OWUI-Frontend-Aenderungen — OWUI ist Plattform, MCP-Layer reicht
  • Multi-Tenant-Architektur fuer mcp-zettle — kommt erst mit Kunde 2
  • Vollstaendige Steuerberater-Anbindung — DATEV-Export reicht erst mal, kein DATEV-Unternehmen-Online-Push
  • Migrations-Logik — Greenfield, keine alten Daten zu uebernehmen
  • Mobile OWUI-App — Web-UI reicht
  • E-Commerce-Webshop — wenn Woehrle online verkaufen will, ist das separates Projekt
  • Eigenbau Kassen-UI — Zettle-App auf Tablet reicht
  • AWS-Hosting — bewusst Hetzner per Kundenwunsch (Marvin-Default waere av-Subaccount in AWS)

Context & Research

Recherche-Quellen (3 Pass-Reports inline, nicht als separate Run-Files)

Pass 1 — POS-Recherche (TSE + API + Self-Service in DE 2026):

  • Zettle gewinnt: 9,90 EUR/Monat Cloud-TSE, Reader direkt online, Product Library + Inventory v3 als Full-POS-REST. Quellen: developer.zettle.com, zettle.com/de/kassensystem.
  • Stripe Terminal raus (keine TSE-DE), SumUp raus (Payment-API ohne Inventory-Endpoints), Tillhub raus (Sales-Funnel).

Pass 4 — POS-Markt-Recheck 2026-05-21 (Best-Practices-Researcher-Run zu Zettle-Alternativen):

  • Verdikt: Zettle bleibt richtige Wahl. Einziger ernsthafter Challenger ist KORONA.pos (Combase, Dresden — stark, aber kein Self-Service-Signup + Hardware-TSE statt Cloud-TSE).
  • ready2order raus wegen Preis (51-56 EUR/Monat vs Zettles 9,90 EUR ohne Mehrwert).
  • Shopify POS, orderbird, enfore, Lightspeed, Vectron: alle aus Use-Case-Gruenden raus.
  • Drei neue Stoerfaktoren bei Zettle identifiziert (jetzt im Risk-Register + Unit 1.1 + Unit 1.3): 99-Varianten-Limit pro Produkt, Soft-Rate-Limit ohne planbare Backoff-Strategie, PayPal-Single-Vendor-Risiko.

Pass 2 + 3 — Buchhaltungs-API:

  • Lexware Office XL (32,90 EUR netto, OAuth2, Sandbox, Webhooks, PayPal-Native, sehr gute Doku unter developer.lexware.io).
  • DevEx-Ranking: Pennylane > Lexware > BuchhaltungsButler > Papierkram > WISO. Pennylane DE-Markt 2026 zu jung (kein DATEV-Kanzlei-Pfad).
  • collmex (15 EUR mit API) raus wegen UI-Endkunden-Tauglichkeit.

Relevante Patterns + Codebases

  • MCP-Eigenbau-Pattern: SKILL — FastMCP v2, stdio + HTTP, .env.local, OpenAPI-Generation, Best-Practices in mcp-best-practices
  • Bestehender mcp-lexware-office (Read-only, 8 Tools): mcp-lexware-office — Basis fuer v2-Ausbau
  • mcp-papierkram als Vorlage fuer ~70-Tools-Pattern: mcp-papierkram — Strukturierung von CRUD-MCPs
  • Hetzner Project-pro-Kunde: projects — Mandanten-Trennung-Pattern
  • MCP-Hosting Fargate-Tunnel-Pattern: mcp-hosting-fargate-tunnel — fuer den Fall dass MCPs ueber Hetzner+CF-Tunnel gehostet werden
  • mcp-vf-hosted als Mono-MCP-Pattern: mcp-vf-hosted — analoge Architektur fuer einen Woehrle-Custom-Connector
  • Festpreis-Pattern fuer Mittelstand-Sales: festpreis-phase1-notausgang — Setup + Monatlich + 4-Wochen-Notausgang

Institutionelle Learnings (relevant)

  • „Nicht alles selber bauen”-Regel (nicht-alles-selber-bauen) — Zettle + Lexware sind SaaS, wir bauen NUR die OWUI-Schicht zwischen Tools, nicht eigene Backends.
  • „Workshop statt Formular”-Regel — Discovery-Call statt PDF-Hausaufgabe an Woehrle.
  • „Keine Email-Einladungen ohne OK”-Regel — alle Kalender-Events erstellen mit sendUpdates=none, dann Marvin-Freigabe.

Key Technical Decisions

EntscheidungBegruendung
Zettle ueber Stripe Terminal / SumUpSelf-Service-Anmeldung Pflicht (Marvin-Wunsch), TSE nativ, Inventory-API als Voll-API (nicht nur Payment), Hardware-Reader online bestellbar.
Lexware Office XL ueber Papierkram/sevDeskPayPal-Native-Anbindung — Zettle laeuft via PayPal-Konto rein, kein Zettle→FiBu-Bridge-Aufwand. Plus: bestehender mcp-lexware-office als Read-only-Basis. Plus: DE-Steuerberater-Akzeptanz beste. Plus: OAuth2 + Sandbox sauberer als Papierkram. Trade-off: 15 EUR/Monat teurer als Papierkram — bei 143 EUR Marge irrelevant.
Hetzner ueber AWSPer Kundenwunsch. Marvins Default ist av-Subaccount in AWS Org o-p197skdqva, aber Woehrle hat Hetzner-Wunsch geaeussert. Geht — intern/capabilities/hetzner/projects.md-Pattern. Trade-off: kein Bedrock-EU fuer LLM-Aufrufe direkt aus Hetzner — entweder OWUI-LLM-Calls ueber Bedrock-Proxy in AWS-av-prod-Account oder direkt Claude/OpenAI-API (Compliance pruefen).
OWUI als KI-Chat-Layer ueber MCPs (nicht Eigenbau-UI)OWUI ist das Frontend-Tool (Multi-User-Chat) das wir Kunden anbieten — fuer Woehrle keine Custom-UI bauen. Custom Connector analog mcp-vf-hosted-Pattern.
Phase-1-Notausgang verbindlich (~20% Setup-Pauschal)Pattern aus festpreis-phase1-notausgang. Nach 4 Wochen: OWUI-Demo gegen Zettle-Test-Account + Lexware-Sandbox lauffaehig. Wenn Woehrle nicht ueberzeugt: Phase-1-Pauschal, kein weiterer Aufwand.
Ticketsystem: hi.events Multi-Tenant Self-Host als Default-Pfadhi.events ist Open-Source-Eventbrite-Alternative (AGPL-3.0), Docker-Compose-Setup mit ~2/5 Komplexitaet, native Stripe Connect, QR-Check-in, Multi-Organizer von Tag 1. Wird auf separatem Hetzner-Project av-events gehostet (NICHT in av-woehrle) und ab Kunde 2 mit Event-Bedarf null-Aufwand-Onboarding. Fallback Cal.com bei AGPL-Lizenz-Blocker, Mini-Pfad Zettle-Artikel bei reiner Tageskasse.
mcp-zettle + mcp-lexware-office v2 + mcp-hi-events in ScopeDrei Standard-Stack-Layer die ueber Woehrle hinaus wiederverwendbar sind. Aufwand verteilen ueber Kunden 1-3, nicht als Woehrle-spezifischer Sunk-Cost positionieren.
AGPL-3.0-Lizenz-Check vor hi.events-CommitAGPL Network-Use-Clause kann SaaS-Vermietung an Kunden problematisch machen — eigene Modifikationen muessten ggf. veroeffentlicht werden. Vor Phase 2 mit hi.events-Devs klaeren (kommerzielle Lizenz-Option erfragen oder bestaetigen dass Self-Host-fuer-Kunden ohne Modifikationen unproblematisch ist). Phase-1-Blocker fuer Pfad A.

Open Questions

Resolved During Planning

  • POS-System: Zettle (Pass 2 + 3 der Recherche festgelegt).
  • Buchhaltung: Lexware Office XL (Pass 3 der Recherche festgelegt).
  • API-Quality fuer MCP-Bau: Lexware Office XL ist „good enough” + bestehender MCP-Basis vorhanden.
  • Self-Service-Anforderung: beide Komponenten erfuellen (Zettle Reader im Shop, Lexware Online-Trial).

Deferred to Implementation

  • Wein-SKU-Anzahl — Discovery-Frage. Bei >500 SKUs ggf. Zettle-Inventory limitiert, dann Bestand-Sub-Layer im OWUI-MCP noetig.
  • Jahrgangs-Modellierung — Discovery-Frage. Empfehlung jeder Jahrgang = eigene SKU (umgeht 99-Varianten-Limit bei Zettle, einfacherer Bestand pro Jahrgang). Wenn Woehrle aus UI-Gruenden Varianten will: bei Jahrgangs-Anzahl <90 OK, sonst architektonisch unsicher.
  • Event-Format Weingalerie — Discovery-Frage. Entscheidet Ticketsystem-Auswahl.
  • Steuerberater-Akzeptanz Lexware — Discovery-Frage. Bei Konflikt: alternativer DATEV-Workflow nach Phase 1.
  • OWUI-LLM-Routing — Phase-2-Detail: Bedrock-Proxy ueber AWS-av-prod oder direkter Anthropic-API-Call von Hetzner? DSGVO-relevant, im OWUI-Repo zu entscheiden.
  • MCP-Hosting — Phase-2-Detail: laufen mcp-zettle + mcp-lexware-office als stdio in OWUI-Container ODER als HTTP-MCPs ueber CF-Tunnel? Stdio reicht fuer Single-Tenant, HTTP brauchts bei Multi-Tenant. Woehrle = Single-Tenant → stdio reicht zunaechst.

Implementation Units

Phase 1 — Technik-MVP (4 Wochen, Notausgang-Punkt)

Phase-Ziel: Lauffaehiger OWUI-Demo gegen Test-Daten. Woehrle entscheidet nach 4 Wochen (durch Alex moderiert) ob Phase 2 startet oder Notausgang.

Arbeitsteilung: Kundenseite (Discovery, Vertrieb, Festpreis-Verhandlung, Champion-Identifikation) liegt bei Alex. Marvin ist auf Technik-Track. Discovery-Outputs (Wein-SKUs, Event-Format, Steuerberater, Hardware) bekommen wir via Alex.

  • Unit 1.1: Discovery-Workshop mit Woehrle — verantwortet durch Alex, technische Outputs an Marvin via internem Briefing

Goal: Vier Discovery-Fragen klaeren, Festpreis-Setup-Angebot bestaetigen, Champion-Onboarding-Pattern etablieren.

Requirements: R1, R2, R4, R5, R6, R7 (alle).

Dependencies: Kalender-Slot mit Woehrle-GF vereinbart, Workshop-Leitfaden vorbereitet.

Files (Vault, intern):

  • Erstellen: intern/kunden/woehrle.md (falls noch nicht vorhanden — Frontmatter Schema Kunde)
  • Erstellen: intern/projekte/woehrle-stack/discovery-workshop-leitfaden.md
  • Erstellen: intern/projekte/woehrle-stack/discovery-protokoll-YYYY-MM-DD.md (nach Workshop)

Approach:

  • Workshop, nicht Formular (workshop-statt-formular)
  • 90 Minuten vor Ort oder per Video
  • Fuenf Pflicht-Fragen: Wein-SKU-Anzahl, Jahrgangs-Modellierung (jeder Jahrgang = eigene SKU vs. Variante — wir empfehlen eigene SKU wegen Zettle-99-Varianten-Limit pro Produkt, siehe Risk-Register), Hardware-Bestand (Tablet/iPad/Bondrucker), Event-Format (VVK oder Tageskasse), Steuerberater + Datev-Workflow
  • Festpreis-Setup-Angebot direkt im Workshop kommunizieren (Pattern: festpreis-phase1-notausgang)
  • Champion bei Woehrle benennen lassen (1 Person die 2 Tage Schulung bekommt + monatliches 30-Min-Review)

Test scenarios:

  • Happy path: alle 4 Pflicht-Fragen beantwortet, Festpreis-Angebot grundsaetzlich akzeptiert, Champion benannt.
  • Edge case: Woehrle zoegert bei Festpreis → Phase-1-Notausgang explizit erklaeren, sonst Verlust-Aversion-Bias hilft.
  • Edge case: Steuerberater bindet Woehrle an anderes FiBu-System → Notausgang, Stack-Entscheidung neu prufen (worst case: Papierkram statt Lexware).

Verification:

  • Discovery-Protokoll im Vault, 4 Fragen schriftlich beantwortet
  • Festpreis-Angebot per Mail an Woehrle gegangen (Skill email-schreiben nutzen)
  • Champion-Name + Kontakt in intern/menschen/<champion-slug>.md
  • Unit 1.2: Zettle-Test-Account + Hardware-Bestellung (Pre-Live-Demo)

Goal: Eigener Zettle-Test-Account live, Demo-Reader im Buero verfuegbar fuer Pre-Sales-Demo gegenueber Woehrle.

Requirements: R1, R4, R9.

Dependencies: PayPal-Business-Account vorhanden (hello@marvinkuehlmann.com), Reader-Hardware-Budget (~99 EUR einmalig).

Files:

  • Erstellen: intern/capabilities/mcps/zettle.md (Setup-Doku-Stub mit „configured”-Status, wird in Unit 1.3 zu „active” befoerdert)
  • Update: _index — Zettle-Zeile in „configured”-Tabelle

Approach:

  • Zettle-Account anlegen ueber zettle.com/de (Self-Service-Signup)
  • TSE-Aktivierung im Onboarding-Flow erledigen (laut Recherche im Lizenzpreis inklusive)
  • Reader Solo bestellen (online-Shop)
  • 5 Test-Wein-SKUs anlegen (Spaetburgunder, Riesling, Pinot Noir, Sekt, Whiskey — mit MwSt-Splits 7%/19% pruefen)
  • 3-5 Test-Transaktionen durchfuehren um Inventar + Sales-API durchzuspielen

Test scenarios:

  • Happy path: Account aktiv, Reader funktioniert mit Tablet/iPad-App, TSE liefert Signaturen pro Transaktion, Belege haben Pflichtfelder (Seriennummer, Signaturzaehler, Transaktions-Endzeit).
  • Edge case: MwSt 7% (Wein) vs 19% (Whiskey) — beide Splits in einem Beleg pruefen.
  • Edge case: Bestand auf 0 → naechster Verkauf darf nicht crashen, sondern Warnung in Inventory-API.

Verification:

  • Zettle-Dashboard zeigt 5 Test-SKUs + 3 Test-Verkaufe
  • API-Test via curl gegen https://oauth.zettle.com (Auth) + https://inventory.izettle.com (Inventory) erfolgreich
  • TSE-Signaturen auf Test-Belegen sichtbar
  • Unit 1.3: mcp-zettle Eigenbau v0.1 (Read-Layer)

Goal: Funktionierender lokaler MCP-Server der Zettle Product Library + Inventory v3 abfragen kann. Read-Only zuerst, write kommt in Phase 2.

Requirements: R3, R4, R6.

Dependencies: Zettle-Test-Account aus Unit 1.2, mcp-eigenbau-Skill gelesen, FastMCP v2 verfuegbar.

Files (Repo-relative zu ~/source/):

  • Erstellen: ~/source/mcp-zettle/ Repo
  • Erstellen: mcp-zettle/.env.local.example (PAYPAL_API_KEY, ZETTLE_USERNAME, ZETTLE_PASSWORD-Hashes)
  • Erstellen: mcp-zettle/src/server.py (FastMCP-Server-Entrypoint)
  • Erstellen: mcp-zettle/src/zettle_client.py (OAuth2 + REST-Wrapper)
  • Erstellen: mcp-zettle/src/tools/products.py (list_products, get_product)
  • Erstellen: mcp-zettle/src/tools/inventory.py (get_inventory_balance, list_inventory_locations)
  • Erstellen: mcp-zettle/src/tools/sales.py (list_sales, get_sale, get_daily_summary)
  • Erstellen: mcp-zettle/tests/test_zettle_client.py
  • Erstellen: mcp-zettle/README.md (Setup + Tools-Liste)
  • Update: _index — neuer Eintrag
  • Update: _index — Zettle-Status von „configured” auf „active”

Approach:

  • FastMCP v2 Pattern aus SKILL
  • stdio-Transport zuerst (Single-Tenant Woehrle), HTTP-Transport vorbereiten aber nicht aktivieren
  • OAuth2-Auth-Layer fuer Zettle (Access-Token-Caching via .cache/zettle-token.json)
  • 6 Tools in Phase-1: list_products, get_product, get_inventory_balance, list_sales, get_daily_summary, get_bestseller_last_7_days
  • Logging mit strukturierten Log-Lines (key=value, kein freier Text)
  • Best-Practices aus mcp-best-practices anwenden (Docstrings, Error-Hints, Raw-Tools-Gating)
  • Response-Caching ist Pflicht, nicht Optimierung — Zettle hat soft rate limits (rollierender Durchschnitt, keine festen Kontingente), Backoff alleine reicht nicht. TTL-Strategie: get_daily_summary und get_bestseller_last_7_days 5 Min Cache, list_products 1 Std Cache, get_inventory_balance 1 Min Cache. Cache-Backend zunaechst in-memory pro MCP-Process, ab Multi-Tenant auf Redis. Quelle: Zettle Inventory v3 — How inventories work
  • 99-Varianten-Limit pro Produkt beachten — wenn Champion Jahrgaenge als Varianten anlegt knallt es bei >99. MCP-Tool list_products muss bei Variant-Count > 90 eine Warnung in den Response-Metadata-Block schreiben. Quelle: Zettle Product Library Management

Patterns to follow:

  • ~/source/mcp-papierkram/ als Struktur-Template
  • mcp-best-practices.md Audit-Checkliste

Test scenarios:

  • Happy path: list_products liefert die 5 Test-SKUs aus Zettle. get_daily_summary mit Datum=heute liefert die 3 Test-Verkaufe summiert. get_bestseller_last_7_days liefert die meist-verkaufte SKU.
  • Edge case: Bestand auf 0 → get_inventory_balance liefert {"stock": 0} sauber, kein Crash.
  • Error path: Falscher API-Key → 401 mit klarer Error-Hint („Token invalid, check .env.local ZETTLE_API_KEY”).
  • Error path: Rate-Limit getroffen → Retry mit Backoff, max 3 Versuche, dann sauberer Error.
  • Integration: MCP-Tool in OWUI-Test-Session aufrufen, Antwort kommt im Chat als strukturierte Daten an.

Verification:

  • 6 Tools listet sich in MCP-Inspector
  • OWUI-Test-Session ruft get_daily_summary und bekommt sinnvolle Antwort
  • Tests gruen (pytest)
  • README erklaert Setup in <5 Min fuer fremden Entwickler
  • Unit 1.4: mcp-lexware-office v2 Write-Erweiterung (CRUD)

Goal: Bestehender Read-only-MCP (8 Tools) erhaelt Write-Faehigkeit fuer Belege, Kontakte, Zahlungen — damit OWUI Belege erstellen und Buchungssaetze fuer Zettle-Tagesabschluesse ablegen kann.

Requirements: R2, R3, R6.

Dependencies: Lexware-Sandbox-Account, OAuth2-App-Credentials in developer.lexware.io registriert, bestehender mcp-lexware-office-Repo.

Files (Repo-relative zu ~/source/):

  • Modify: mcp-lexware-office/src/server.py (neue Write-Tools registrieren)
  • Erstellen: mcp-lexware-office/src/tools/invoices.py (create_invoice, update_invoice, delete_invoice_draft)
  • Erstellen: mcp-lexware-office/src/tools/contacts.py (create_contact, update_contact)
  • Erstellen: mcp-lexware-office/src/tools/payments.py (create_voucher, attach_receipt_to_voucher)
  • Modify: mcp-lexware-office/tests/test_write_paths.py (neu)
  • Update: README mit neuer Tools-Liste
  • Update: mcp-lexware-office — Status read-only → full-CRUD
  • Update: lexware — Tools-Anzahl ~8 → ~20

Approach:

  • OAuth2-Refresh-Token-Flow sauber (kein API-Key wie in Read-only-v1)
  • Idempotency-Keys bei create_invoice einbauen (UUID4) — kein Duplikat bei Retry
  • Sandbox-Mode-Flag via Env-Var, damit Tests gegen Sandbox laufen, produktion gegen prod
  • Schema-Validation via Pydantic vor API-Call (keine Server-500-Loops)
  • DATEV-Export-Tool als Pflicht: export_datev_csv(period_start, period_end) → DATEV-konforme CSV

Patterns to follow:

  • mcp-papierkram CRUD-Tool-Struktur (saubere Trennung Read/Write)
  • mcp-best-practices.md Error-Handling-Sektion

Test scenarios:

  • Happy path: create_invoice mit minimalem Body liefert Lexware-ID zurueck, Sandbox zeigt Rechnung im UI.
  • Happy path: create_voucher mit Anhang-Datei (PDF) bindet Beleg an Buchungssatz.
  • Edge case: create_invoice mit nicht-existentem Kontakt → klarer Error-Hint, kein Server-Crash.
  • Edge case: Idempotency — create_invoice zweimal mit gleichem Key → zweiter Call gibt erste-ID zurueck, kein Duplikat.
  • Error path: OAuth-Token abgelaufen → automatisches Refresh, dann Retry.
  • Error path: Lexware-Rate-Limit (5 req/s) → Exponential-Backoff, max 3 Versuche.
  • Integration: export_datev_csv fuer Testperiode → CSV ist DATEV-Format-konform (Spaltenzahl, Encoding ISO-8859-15).

Verification:

  • ~20 Tools listet sich in MCP-Inspector
  • End-to-End-Test: Tag-Abschluss von Zettle (via mcp-zettle.get_daily_summary) → Buchungssatz in Lexware (via mcp-lexware-office.create_voucher)
  • DATEV-Export laed sich in Steuerberater-Tool ohne Format-Fehler
  • Unit 1.5: OWUI-MVP-Demo gegen Test-Daten

Goal: OWUI-Custom-Connector laeuft lokal, ruft mcp-zettle + mcp-lexware-office ueber MCP-Layer, beantwortet 5 Pre-Sales-Fragen.

Requirements: R3, R6.

Dependencies: Unit 1.3 + 1.4 fertig, OWUI-Repo (~/source/apps/open-webui-vf/ (Pattern-Vorlage)) lauffaehig, Anthropic-API-Key in .env.local.

Files (Repo-relative zu ~/source/apps/open-webui-vf/ (Pattern-Vorlage)):

  • Modify: open-webui/config/mcp-servers.yaml (Eintraege fuer mcp-zettle + mcp-lexware-office stdio)
  • Modify: open-webui/prompts/system.md (Stack-Context fuer Wein-Vertical: „Du bedienst einen Weinhandel mit Galerie”)
  • Erstellen: open-webui/demos/woehrle-mvp/ (Demo-Szenario mit 5 Beispiel-Fragen)

Approach:

  • Stdio-MCP-Hosting innerhalb OWUI-Container (kein HTTP-Tunnel noetig fuer Single-Tenant)
  • 5 Demo-Fragen festlegen, gegen Zettle-Test-Account + Lexware-Sandbox getestet:
    1. „Was war gestern unser Tagesumsatz?” → mcp-zettle.get_daily_summary
    2. „Welcher Wein verkauft sich am besten?” → mcp-zettle.get_bestseller_last_7_days
    3. „Wie viel Riesling haben wir noch auf Lager?” → mcp-zettle.get_inventory_balance
    4. „Erstelle Rechnung fuer Eventbuchung X EUR an Kunde Y” → mcp-lexware-office.create_invoice
    5. „Wie viel Umsatz im April mit MwSt 7%?” → mcp-zettle.list_sales + Aggregation
  • Performance-Ziel: <3s Antwortzeit pro Frage

Patterns to follow:

  • mcp-vf-hosted als Vorbild fuer Custom-Connector-Architektur (auch wenn Woehrle nicht im claude.ai-Connector laeuft)
  • Best-Practices OWUI-System-Prompt (existieren im OWUI-Repo)

Test scenarios:

  • Happy path: alle 5 Fragen liefern sinnvolle Antwort in <3s.
  • Edge case: Frage mit Bezug auf SKU die nicht existiert → klarer „nicht gefunden”-Hinweis, kein Halluzinieren.
  • Edge case: Beleg-Erstellung schlaegt fehl wegen Lexware-Sandbox-Limit → OWUI gibt Fehler-Hint zurueck statt zu halluzinieren dass es geklappt hat.
  • Integration: Demo-Walkthrough Skript laufen lassen (5 Fragen sequentiell) → kein Crash, alle Antworten plausibel.

Verification:

  • Demo-Video aufgenommen (Screencap, 2-3 Min) das Marvin Woehrle in Phase-1-Praesentation zeigen kann
  • 5 Fragen end-to-end gruen
  • OWUI-Logs zeigen MCP-Tool-Calls + Response-Times

Phase 2 — Live-Stack bei Woehrle (Wochen 5-10)

Phase-Ziel: Echter Stack live im Wein-Laden, Woehrle nutzt Zettle als Kasse, Lexware als FiBu, OWUI fuer 5 Use-Cases.

Notausgang-Check vor Phase 2-Start: Woehrle muss schriftlich Phase 1 akzeptieren. Wenn nein: Phase-1-Pauschal beenden.

  • Unit 2.1: Hetzner-Project av-woehrle + Infrastruktur

Goal: Dediziertes Hetzner-Projekt mit CX22-Server, Cloudflare-Tunnel, Object-Storage-Backup.

Requirements: R7.

Dependencies: Hetzner-Account, Cloudflare-Account (Domain agenticventures.de aktiv).

Files (Vault):

  • Erstellen: intern/capabilities/hetzner/av-woehrle.md (Pattern aus projects)
  • Update: projects — neuer Project-Eintrag

Approach:

  • Hetzner-Cloud-API via mcp-hetzner nutzen, NICHT UI-Klickerei
  • CX22 in nbg1 (Nuremberg, EU)
  • Ubuntu 24.04 LTS, Docker-Compose-Stack
  • Cloudflare-Tunnel mcp-woehrle.agenticventures.de (subdomain auf av-Domain) fuer OWUI-MCP-Hub
  • Object-Storage-Bucket av-woehrle-backups fuer DSGVO-konforme Backup-Aufbewahrung
  • Firewall: nur 22 (SSH von Marvin), 80/443 (CF-Tunnel-Egress)

Patterns to follow:

Test scenarios:

  • Happy path: Server pingbar, CF-Tunnel-Endpoint erreichbar, Backup laeuft naechtlich auf Object-Storage.
  • Edge case: Server-Reboot → Tunnel kommt selbststaendig zurueck (systemd-Service).
  • Error path: API-Key falsch → klarer Error im Setup-Script, kein Halb-Setup.

Verification:

  • mcp-woehrle.agenticventures.de antwortet mit 200 auf /healthz
  • Backup-Bucket zeigt letzte 7 Tage
  • Vault-Eintrag aktualisiert
  • Unit 2.2: Zettle Live-Account + Hardware bei Woehrle

Goal: Woehrles Zettle-Account aktiv, Reader im Laden, Bestand und Personal eingerichtet.

Requirements: R1, R4, R9.

Dependencies: Unit 1.1 Discovery abgeschlossen (Wein-SKU-Anzahl bekannt), Hardware bestellt oder vorhanden.

Files:

  • Update: intern/projekte/woehrle-stack/_index.md — Status auf „delivery”
  • Erstellen: intern/projekte/woehrle-stack/woehrle-zettle-config.md (Inventar-Setup-Doku)

Approach:

  • Zettle-Account fuer Woehrle (Champion-User-Anlage)
  • Wein-SKUs migrieren — Bulk-Upload CSV mit Marvin und Champion 2h Workshop
  • TSE-Aktivierung + ELSTER-Meldung mit Champion durchgehen
  • 2 Tage Champion-Schulung (Festpreis-Pattern-Pflicht)

Test scenarios:

  • Happy path: Champion kann alleine Verkauf abwickeln, Beleg drucken, Bestand pruefen.
  • Edge case: Wein-SKU mit MwSt 7% UND Whisky mit 19% in einem Beleg → korrekt aufgeteilt.
  • Edge case: Reader-Bluetooth-Verbindung verloren → App zeigt klaren Hint zum Reconnect.

Verification:

  • Champion abnahme: 5 echte Verkaufe ohne Marvin-Support
  • ELSTER-Meldung bestaetigt
  • Token-Konfig in Hetzner-av-woehrle-Env-Vars
  • Unit 2.3: Lexware Office XL Live-Account + Anbindungs-Setup

Goal: Woehrles Lexware-Account aktiv, PayPal-Konto verknuepft, DATEV-Export an Steuerberater getestet.

Requirements: R2.

Dependencies: Unit 1.1 Discovery, Steuerberater bekannt + DATEV-Workflow geklaert.

Files:

  • Erstellen: intern/projekte/woehrle-stack/woehrle-lexware-config.md (Tarif, Kontenrahmen, Steuerberater-Workflow)

Approach:

  • Lexware Office XL-Tarif buchen (~39 EUR/Monat brutto)
  • PayPal-Konto verknuepfen (Lexware PayPal-Doku)
  • Kontenrahmen SKR03 oder SKR04 mit Steuerberater abstimmen (Workshop-Frage)
  • DATEV-Export-Test mit Steuerberater (Probe-Datei)
  • OAuth2-App fuer OWUI registrieren (developer.lexware.io)

Test scenarios:

  • Happy path: PayPal-Konto sync, Zettle-Tagesabschlusse landen automatisch als Buchungssatz in Lexware.
  • Edge case: Steuerberater meldet DATEV-Import-Fehler → Format pruefen, fix.
  • Error path: OAuth2-Refresh-Token expired → Auto-Refresh, kein Manuell-Eingriff.

Verification:

  • Erster Monat live: Lexware enthaelt alle Zettle-Transaktionen ohne manuellen Abgleich
  • DATEV-Export erfolgreich an Steuerberater
  • OWUI-OAuth2-Flow getestet (mcp-lexware-office v2 schreibt Test-Beleg)
  • Unit 2.4: Ticketsystem-Entscheidung implementieren — hi.events Self-Host als Default

Goal: Multi-Tenant Event-Ticketing-Plattform auf Hetzner aufgesetzt — wiederverwendbar fuer alle kuenftigen Kunden mit Event-Bedarf (Weinhandel, Restaurants, Galerien, Friseure-mit-Workshops, Yogastudios). Erster Tenant ist Woehrle, Architektur ist Multi-Organizer von Tag 1.

Requirements: R5.

Dependencies: AGPL-Lizenz-Check ergibt SaaS-Anbieten ist OK (Action-Item, vor Phase 2 klaeren), Hetzner-Project av-events separat von av-woehrle (weil Multi-Tenant — gehoert nicht ins Kunden-Projekt sondern in unsere Plattform-Schicht).

Files (Vault + Repos):

  • Erstellen: intern/capabilities/apps/hi-events-av.md (Plattform-Doku analog open-webui-vf.md-Pattern)
  • Erstellen: intern/capabilities/hetzner/av-events.md (separates Hetzner-Project fuer die Plattform)
  • Erstellen: ~/source/mcp-hi-events/ Repo (FastMCP v2, analog mcp-zettle-Pattern)
  • Erstellen: intern/projekte/woehrle-stack/woehrle-hi-events-tenant-config.md (Woehrle-spezifische Organizer-Config + Event-Templates)
  • Update: _index — neuer Eintrag mcp-hi-events
  • Update: _index — neuer Eintrag mcp-hi-events
  • Update: produkt-bundle — Event-Ticketing als Plattform-Capability ergaenzen

Approach (Pfad A Default — hi.events Self-Host):

  • Multi-Tenant-Plattform NICHT in av-woehrle sondern eigenes Hetzner-Project av-events (Pattern: einmal aufgesetzt, alle Kunden bekommen Organizer-Account drin)
  • Docker-Compose-Setup aus HiEventsDev/hi.events (docker/all-in-one/)
  • Hetzner CX22 in nbg1 mit Cloudflare-Tunnel-Subdomain tickets.agenticventures.de
  • Pro Kunde eigene Subdomain via Wildcard-CF-Tunnel (z.B. woehrle.tickets.agenticventures.de oder events-woehrle.agenticventures.de)
  • Stripe Connect — Woehrle hat eigenen Stripe-Account, Payouts gehen direkt an Woehrle (kein Treuhand-Risiko bei uns)
  • Branding pro Organizer via hi.events-eigene Theming-Faehigkeit
  • mcp-hi-events neu bauen (FastMCP v2, REST-API von hi.events wrappen, ~2 TW) — Tools: list_events, get_event, list_tickets_sold, get_event_revenue, create_event_draft, list_attendees, cancel_order
  • OWUI-Use-Case: Woehrle fragt „wieviele Tickets fuer Riesling-Abend?” → mcp-hi-events
  • Belegfluss zu Lexware via Stripe-Verbindung (PayPal-Native bei Lexware funktioniert auch fuer Stripe-Konto)

Approach Pfad B (Fallback) — Cal.com + Stripe:

  • Falls AGPL-Check ergibt dass Multi-Tenant-SaaS-Hosting problematisch ist
  • Aufwand 1 TW, kein neuer MCP noetig (bestehender mcp-calcom reicht)
  • Cal.com-Event-Types mit Capacity + Stripe-Payment
  • Schwaechere Branding-Story, kein QR-Check-in

Approach Pfad C (Mini) — Zettle-Artikel:

  • Falls Woehrle im Discovery sagt „nur Tageskasse, kein Online-VVK”
  • 0 TW, keine zusaetzliche Infrastruktur
  • Eventtickets als Zettle-SKU mit Kategorie „Event”

Patterns to follow:

Test scenarios:

  • Happy path: Test-Organizer „Demo-Weingalerie” angelegt, Test-Event mit 12 Plaetzen, 49 EUR/Ticket, 5 Test-Tickets verkauft, QR-Codes generiert, Check-in mit Mobile-App funktioniert.
  • Happy path: OWUI-Frage „wieviele Tickets fuer Event X?” → mcp-hi-events.get_event liefert korrekte Zahl.
  • Edge case: Event ausverkauft (12/12) → 13. Kauf blockiert mit klarer User-Fehlermeldung.
  • Edge case: Storno-Anfrage → cancel_order triggert Stripe-Refund, Beleg-Reversal in Lexware.
  • Edge case: 2 Organizer in einer Instanz → Daten-Isolation gewaehrleistet (Woehrle sieht nicht Kunde-2-Events).
  • Error path: hi.events-Container down → OWUI gibt klare Fehler-Hint, kein Halluzinieren.
  • Error path: Stripe-Webhook verloren → Reconciliation-Job nach 24h prueft offene Bookings.
  • Integration: end-to-end Ticket-Verkauf (Landing-Page → Stripe-Checkout → hi.events-Order → Email-Bestaetigung mit QR → Check-in vor Ort).

Verification:

  • hi.events-Instanz erreichbar unter tickets.agenticventures.de
  • Mindestens 1 Demo-Event + 5 verkaufte Test-Tickets in Test-Organizer
  • mcp-hi-events listet sich in MCP-Inspector mit ~7 Tools
  • Plattform-Doku hi-events-av.md enthaelt Onboarding-Schritte fuer neue Organizer (in <30 Min auf neuem Kunden ausrollbar)
  • Unit 2.5: OWUI-Produktion bei Woehrle (5 Use-Cases live)

Goal: OWUI-Instanz produktiv, Woehrle nutzt 5 Use-Cases im Alltag.

Requirements: R6.

Dependencies: Units 2.1-2.4 abgeschlossen, Champion eingeschult.

Files:

  • Modify: open-webui/config/customers/woehrle.yaml (Customer-Config im OWUI-Repo)
  • Erstellen: intern/projekte/woehrle-stack/voit-handbuch-woehrle.md (Champion-Doku, 5 Use-Cases)

Approach:

  • OWUI-Container auf Hetzner-CX22 (av-woehrle) lauft mit MCP-Stack
  • 5 produktive Use-Cases (siehe Unit 1.5 Demo-Fragen) — angepasst auf Woehrle-Daten
  • Champion-Onboarding 2 Tage vor Ort
  • Monatliches 30-Min-Review etablieren (Pattern Festpreis-Notausgang)

Test scenarios:

  • Happy path Live: Champion stellt jede der 5 Fragen, korrekte Antwort in <3s.
  • Edge case: Multi-User-Zugriff (Champion + Marvin) → keine Race-Conditions.
  • Error path: Lexware oder Zettle-API down → OWUI gibt klare Fehler-Hint, kein Halluzinieren.
  • Integration: Tagesumsatz-Use-Case end-to-end (Zettle → mcp-zettle → OWUI → Champion-Chat) klappt 5x in Folge.

Verification:

  • 1 Woche Live-Betrieb ohne Eingriff Marvin
  • Champion-Review nach 2 Wochen: 5 Use-Cases werden taeglich genutzt
  • Monitoring: kein API-Error >0.5% Rate

Phase 3 — Operations + Handover (Wochen 11-12)

Phase-Ziel: SLA-fertig, Handover an Woehrle, 6-Monate-Garantie-Pflicht etabliert.

  • Unit 3.1: DSGVO + AVV-Vertrag

Goal: Auftragsverarbeitungs-Vertrag mit Woehrle unterschrieben, DSGVO-Doku komplett.

Requirements: R7 (compliance).

Files:

  • Erstellen: extern/outbound/woehrle/avv-2026-XX.pdf (analog avv-musterxx-Pattern)
  • Erstellen: intern/projekte/woehrle-stack/dsgvo-checkliste.md

Approach:

  • AVV-Mustertext aus Vault-Vorlage anpassen
  • Daten-Kategorien dokumentieren (Kunden-Stammdaten, Verkaufs-Daten, Beleg-PDFs)
  • Sub-Processors: PayPal/Zettle, Lexware GmbH, Hetzner Online GmbH, Anthropic (LLM)
  • 10-Jahre-Aufbewahrungs-Konzept (GoBD-Pflicht) auf Object-Storage Bucket-Lock

Verification:

  • AVV unterschrieben (beide Seiten)
  • DSGVO-Checkliste komplett
  • TOM (technische und organisatorische Massnahmen) Beilage geliefert
  • Unit 3.2: Champion-Handover + SLA

Goal: Woehrles Champion arbeitet autonom, monatliches Review etabliert, SLA dokumentiert.

Files:

  • Erstellen: extern/outbound/woehrle/sla-2026-XX.pdf
  • Erstellen: intern/projekte/woehrle-stack/monatliches-review-template.md
  • Update: active-work — Woehrle-Status auf „live”

Approach:

  • 2 Tage Champion-Schulung (Pattern-Pflicht)
  • SLA-Doku: 4h Geschaeftszeit-Reaktion, 24h ausserhalb, 8h/Monat Anpassungen inkl.
  • 6-Monate-Garantie schriftlich
  • Monatliches 30-Min-Review-Termin als wiederkehrender Kalender-Event (mit Woehrle-Bestaetigung, siehe Email-Einladungs-Regel)

Verification:

  • Champion-Schulungs-Protokoll
  • Erster monatlicher Review-Termin im Kalender
  • Woehrle-Eintrag in active-work auf „live + recurring”
  • Unit 3.3: Pattern-Destillat + Standard-Stack-Layer

Goal: Erfahrungen aus Woehrle-Projekt als wiederverwendbares Pattern festhalten, mcp-zettle und mcp-lexware-office v2 als Standard-Stack-Layer dokumentieren.

Files:

  • Erstellen: intern/wissen/patterns/weinhandel-stack-pattern.md (oder allgemeiner kmu-zettle-lexware-stack-pattern.md)
  • Update: _index — mcp-zettle eingehakt
  • Update: produkt-bundle — neuer Tier „KMU-Retail-Bundle” mit Zettle + Lexware + OWUI

Approach:

  • ce:compound-Skill nutzen — destillieren was wiederverwendbar ist
  • 3-5 Lessons-Learned als Bullet-Points
  • Festpreis-Setup-Spannweite dokumentieren (was war 11k EUR vs. 16k EUR Setup-Treiber?)

Verification:

  • Pattern-Doc existiert, ist im Vault verlinkt
  • Naechster Kunde mit aehnlichem Profil bekommt das Bundle als Setup-Vorlage

System-Wide Impact

  • MCPs neu/erweitert: mcp-zettle (neu), mcp-lexware-office v2 (write-Erweiterung), mcp-hi-events (neu — Pfad A) — alle drei werden Standard-Stack-Layer
  • Hetzner-Projects-Inventar: zwei neue Eintraege in projects — av-woehrle (Kunden-Stack) plus av-events (Multi-Tenant-Event-Plattform, kunden-uebergreifend)
  • OWUI-Repo-Aenderungen: neue Customer-Config + System-Prompt-Anpassung fuer Wein-Vertical, MCP-Stack-Konfig
  • Plattform-Layer waechst: hi.events als neue „App-as-a-Service”-Capability analog zu open-webui-vf — ab Kunde 2 mit Event-Bedarf null-Aufwand-Onboarding (Organizer-Account in <30 Min)
  • Vault-Doku: neuer Projekt-Eintrag in intern/projekte/, neue Capability-Doku intern/capabilities/apps/hi-events-av.md, neuer Kunden-Eintrag in intern/kunden/, Pattern-Doc nach Live-Gang
  • Active-Work-Liste: Eintrag in active-work beim Discovery-Start und beim Live-Gang aktualisieren
  • Produkt-Bundle erweitert: Event-Ticketing als optionale Capability im KMU-Retail-Bundle (produkt-bundle)
  • Unchanged invariants: Marvins AWS-First-Hosting-Default bleibt fuer andere Kunden gueltig — Woehrle ist explizite Hetzner-Ausnahme per Kundenwunsch.

Risks & Dependencies

RiskWahrscheinlichkeitImpactMitigation
Steuerberater lehnt Lexware abmittelhochDiscovery-Frage adressiert, Notausgang nach Phase 1 — Alternative Papierkram-Stack
Wein-SKUs >500 sprengen Zettle-Inventoryniedrigmittelim Discovery klaeren, ggf. SKU-Konsolidierung empfehlen oder mcp-zettle-Cache-Layer
ELSTER-Meldung wird verzoegert / Finanzamt-RueckfragenmittelniedrigDiscovery: Champion macht Meldung mit Marvin gemeinsam, Standardprozess
Zettle-API-Aenderungen oder Rate-Limitsniedrigmittelmcp-zettle mit Versions-Pinning + Retry-Logic, Monitoring auf Rate-Limit-Hits
Zettle Soft-Rate-Limit (rollierender Schnitt, keine festen Kontingente) → unvorhersehbare Drosselung im MCPmittelmittelResponse-Caching im mcp-zettle als Pflicht (Unit 1.3 Approach), TTLs pro Tool, Cache-Hit-Rate-Monitoring
Zettle 99-Varianten-Limit pro Produkt → Champion legt Jahrgaenge als Varianten an, Inventory-Push schlaegt fehlmittelmittelDiscovery-Pflicht-Frage zur Jahrgangs-Modellierung (Unit 1.1), Empfehlung jeder Jahrgang = eigene SKU, MCP-Warnung bei Variant-Count >90
PayPal-Single-Vendor-Risiko (Praezedenz PayPal Here US-Deprecation 2023)niedrighochDaten-Portabilitaet bei Zettle pruefen vor Live-Gang, im Risk-Register fuer Folgekunden vermerken — fuer Woehrle akzeptabel, fuer Industriekunden ggf. KORONA.pos als Alternative
Lexware-OAuth2-App-Approval dauertmittelmittelApp-Antrag fruehzeitig in Phase 1 stellen, parallel mcp-zettle bauen
Hetzner-Region-Ausfallsehr niedrighochObject-Storage-Backup in anderem Hetzner-Standort, RTO 4h dokumentiert
OWUI-Code aendert sich, Customer-Config brichtniedrigmittelOWUI-Repo-Tag fuer Woehrle-Release pinnen, vor Major-Updates testen
Phase-1-Notausgang wird gezogenniedrigniedrigPhase-1-Pauschal deckt Aufwand, mcp-zettle + mcp-lexware-office v2 + mcp-hi-events bleiben als Standard-Stack-Layer im Portfolio (Investment nicht verloren)
AGPL-3.0-Lizenz blockiert hi.events-Multi-Tenant-HostingmittelmittelLizenz-Check VOR Phase-2-Start in Action-Items. Bei Blocker: Pfad B (Cal.com) ohne Verzoegerung — mcp-calcom ist live
hi.events v1.9-beta-Bug in ProductionmittelmittelVersion-Pin auf getesteten Release, Hetzner-Snapshot taeglich, RTO 30 Min — bei Woehrle als erstem Kunden noch im Phase-1-Garantie-Fenster
Woehrle-Champion verlaesst FirmaniedrighochBackup-Champion einrichten, monatliches Review als „Wissens-Transfer” framen
DSGVO-Vorfall (Sub-Processor-Bruch)sehr niedrighochAVV unterschrieben mit allen Sub-Processors, Incident-Response-Doku im Vault

Documentation / Operational Notes

  • Setup-Pauschale-Spannweite: 11.000-16.000 EUR netto (14-20 Tagewerke). Phase-1-Notausgang: 2.500-3.500 EUR (~20%)
  • Monatliche Recurring: 200 EUR brutto, davon Marge ~143 EUR
  • Setup-Dauer: 12 Wochen, 3 Phasen (Discovery+MVP, Live-Stack, Operations)
  • Champion-Pflicht: 1 Person bei Woehrle mit 2 Tagen Schulung + monatliches 30-Min-Review (Pattern-Pflicht)
  • 6-Monate-Garantie: wenn zugesicherte 5 Use-Cases nicht stabil laufen, Fix ohne Mehrkosten
  • Monitoring: Uptime-Robot fuer mcp-woehrle.agenticventures.de, Sentry fuer OWUI-Errors, CloudWatch-Aequivalent (Hetzner-eigenes Metrics) fuer CX22
  • Rollback-Plan: falls OWUI-Update bricht: Hetzner-Snapshot-Restore (RTO 30 Min), Zettle + Lexware laufen unabhaengig weiter, kein Daten-Verlust
  • Externe Kommunikation: Marvin ist Ansprechpartner, Email an hello@marvinkuehlmann.com, Telefon-Eskalation moeglich
  • Vertraulichkeit: Woehrle-Name nicht in extern-gerichteten Texten erwaehnen (Regel 22) — generisch als „Weinhandel-Kunde NRW” referenzieren in Akquise-Material

Sources & References

Graphansicht

Backlinks