Surface audit generations on dashboard audits

v2_elemente/PitchFast_PRD_v3.md

@@ -0,0 +1,381 @@
+# Product Requirements Document: PitchFast.io
+### Lokaler Akquise-Agent für Webdesign — SaaS-Edition (Deutschland zuerst)
+
+**Version:** 3.1 · **Stand:** Juni 2026 · **Status:** Planung
+**Vorgänger:** v1 (internes Tool, Playwright-self-hosted) → v2 (serverless, AppSumo-Vorbereitung) → v3 (Multi-Tenant-SaaS, DE-first, Compliance- und Unit-Economics-gehärtet) → **v3.1 (SaaS-Abo als primäres Geschäftsmodell durchgerechnet, LTD sekundär)**
+
+> **Was sich gegenüber v2 ändert:** v2 hatte den *technischen* Stack auf serverlos umgestellt, aber Geschäftsmodell, Recht und Mandantenfähigkeit noch wie beim internen Tool behandelt. v3 schließt diese Lücken: echtes Multi-Tenant-Modell, ein durchgerechnetes Geschäftsmodell mit realen API-Kosten (**SaaS-Abo als primäres Modell mit ≥75 % Bruttomarge; LTD nur sekundär und BYO-only**), Compliance als Produktfeature statt als Disclaimer, sowie ein **BYO-Architekturprinzip** (eigene API-Keys + eigenes Postfach pro Kunde), das gleichzeitig das Unit-Economics-Problem *und* das Haftungsproblem löst.
+
+---
+
+## 1. Produktvision und Problemstellung
+
+PitchFast.io ist eine deutsche B2B-SaaS-Plattform, die Webdesignern, kleinen Agenturen und SEO-Freelancern hochwertige lokale Akquise ermöglicht — ohne generische Massenmails. Das Tool findet lokale Unternehmen, führt ein nachvollziehbares Website-Mini-Audit durch (Struktur, Copy, Performance, visueller Eindruck) und bereitet daraus persönliche, datengestützte Erstkontakte vor, die der Nutzer manuell freigibt und versendet.
+
+**Kernproblem:** Manuelle Website-Analyse und echte Personalisierung kosten pro Lead Stunden. Generischer Massen-Spam konvertiert nicht, schadet der Absender-Reputation und ist in Deutschland rechtlich riskant.
+
+**Lösung:** PitchFast automatisiert Recherche und Audit über eine schlanke, serverlose Pipeline und befähigt Nutzer zu chirurgisch präzisem, „account-based" Outreach in kleiner Stückzahl. Qualität vor Menge ist nicht nur Positionierung, sondern reduziert zugleich Kosten- und Rechtsrisiko.
+
+---
+
+## 2. Strategische Leitplanken
+
+Diese Prinzipien sind übergeordnet und entscheiden in Zweifelsfällen die Detailplanung:
+
+1. **Deutschland zuerst — aber markt-konfigurierbar, nicht markt-hartkodiert.** Deutschland ist eine der strengsten Anti-Spam-Zonen (UWG). Wir bauen compliant-by-default für DE. Internationale Expansion ist *kein* Gratis-Carry-over (CASL/Kanada ist auf der Consent-Achse strenger, CAN-SPAM/USA laxer-aber-kompetitiver), deshalb sind Versandregeln, Opt-out-Fristen und Rechtsgrundlagen-Logik pro Markt konfigurierbar, nicht fest verdrahtet.
+2. **BYO everything als Default.** Kunden bringen ihre eigenen API-Keys (Google, OpenRouter, ScreenshotOne) und ihr eigenes Postfach mit. Das verschiebt variable Kosten *und* rechtliche Verantwortung an den Kunden und macht das LTD-Modell tragfähig. Ein „Managed"-Modus mit aufgeschlagenen Credits ist die kostenpflichtige Alternative für nicht-technische Nutzer.
+3. **Qualität vor Menge.** Harte, niedrige Limits pro Lauf. Kein „Unlimited".
+4. **Kein Autopilot.** Versand niemals ohne manuelle Freigabe — architektonisch erzwungen, nicht nur per Policy.
+5. **Compliance als Feature.** Quellen-Dokumentation, Opt-out, Impressums-Block, Sperrfristen und AVV sind verkaufbare Funktionen, kein Kleingedrucktes.
+6. **Dogfooding.** Matthias ist erster Nutzer und Referenzkunde; jedes Feature muss seinen eigenen Akquiseprozess real verbessern, bevor es verallgemeinert wird.
+
+---
+
+## 3. Zielgruppe und Positionierung
+
+### 3.1 MVP-Nutzer / Referenzkunde: Matthias Meister
+Solo-Freelancer im Webdesign (Crimmitschau). Braucht ein dichtes, scanbares Arbeits-Dashboard, das Recherche, Audit, Review, Freigabe, Versand und Follow-up bündelt. Validiert das Produkt im echten Einsatz.
+
+### 3.2 SaaS-Zielgruppe (DE)
+Wachstumsorientierte Webdesigner, kleine Web-/Digitalagenturen und SEO-Freelancer in Deutschland, die einen skalierbaren, aber sauberen Outbound-Kanal suchen und keine eigene Audit-/Outreach-Pipeline bauen wollen.
+
+### 3.3 Positionierung
+- **Boutique-Pricing, Qualität statt Volumen.** Ein gewonnener Webdesign-Auftrag ist mehrere tausend Euro wert; das Tool muss nur wenige Abschlüsse ermöglichen, um sich zu rechnen.
+- **„Compliant German Outreach" als USP.** In einem Markt, in dem Abmahnungen real sind, ist eingebaute Rechtskonformität ein Verkaufsargument, kein Bremsklotz.
+- **Nachhaltige Limits statt „Unlimited"-Versprechen.** Schützt die Marge und die Reputation aller Nutzer.
+
+### 3.4 AppSumo-Eignung (Hinweis)
+Ein AppSumo-Launch bleibt eine *Option*, ist aber nicht handlungsleitend für das MVP. Falls verfolgt, gilt das LTD-Modell in Abschnitt 4. Wichtig: AppSumo erzwingt vollständige Mandantenfähigkeit, Self-Service-Onboarding, Lizenz-Code-Einlösung und belastbare Unit Economics — alles in v3 berücksichtigt. AppSumos Umsatzbeteiligung (Planungsannahme ~30 %, vor Launch verifizieren) und die LTD-Mechanik sind in Abschnitt 4 eingerechnet.
+
+---
+
+## 4. Geschäftsmodell und Unit Economics
+
+> **Dies ist die Gating-Sektion.** Wenn die Stückkosten das Preismodell nicht tragen, ist alles andere irrelevant.
+
+### 4.1 Reale API-Kosten (Stand Mitte 2026 — vor Launch erneut verifizieren)
+
+Alle Preise in USD (Quellwährung der Anbieter). EUR ≈ USD × 0,92.
+
+**Pro Deep-Audit:**
+
+| Komponente | Annahme | Kosten |
+|---|---|---|
+| LLM (GPT-5.4 mini, OpenRouter): $0,75/M Input, $4,50/M Output | ~15–20k Input-Token (Markdown 4 Seiten + 2 Screenshots als Vision-Input + skills.md) + ~3–5k Output inkl. Reasoning | **~$0,025–0,035** |
+| Screenshots (ScreenshotOne ~$0,0085/Shot) | Desktop + Mobile = 2 Shots | **~$0,017** |
+| Copy-Extraktion (Jina AI Reader) | 4 Seiten, token-/anfragebasiert | **~$0,002–0,005** |
+| PageSpeed Insights | kostenlose Quota | **$0,00** |
+| **Summe pro Audit** | | **~$0,045–0,06** |
+
+**Pro Lead (Recherche):**
+
+| Komponente | Annahme | Kosten |
+|---|---|---|
+| Text/Nearby Search (Places, Pro ~$0,032/Call, bis zu 20 Ergebnisse) | amortisiert auf ~20 Leads | **~$0,002/Lead** |
+| Place Details (Pro ~$0,017/Call) | 1 Call je Lead | **~$0,017** |
+| Contact Data SKU (~$0,003/Call, für Telefon/Website) | 1 je Lead | **~$0,003** |
+| Geocoding (~$0,005/Call) | 1 je Kampagne, vernachlässigbar | **~$0,00** |
+| **Summe pro qualifiziertem Lead** | | **~$0,02–0,025** |
+
+**Realistische Gesamtkosten „Lead gefunden + auditiert + Outreach entworfen": ~$0,07–0,09.**
+
+> ⚠️ Das ist das **3- bis 4-fache** der in v2 genannten $0,02. Das alte Erfolgskriterium „unter $0,02 pro Deep-Audit" war nicht haltbar und wurde in Abschnitt 17 ersetzt. Hinweis: Google hat 2026 das Places-Preismodell auf SKU-/Field-Mask-Basis umgestellt; Contact-/Atmosphere-Daten kosten extra, und die Free-Tier-Caps (pro SKU pro Monat) sind schnell aufgebraucht. Volumen treibt die Places-Kosten überproportional.
+
+### 4.2 Drei Kosten-Modi: Wer trägt die variablen Kosten?
+
+Die Stückkosten aus 4.1 muss jemand tragen. Daraus ergeben sich drei Modi:
+
+1. **BYO-Keys (Default, empfohlen):** Der Kunde hinterlegt eigene Keys für Google/OpenRouter/ScreenshotOne. Die variablen Kosten fallen direkt bei ihm an. PitchFasts Grenzkosten pro Nutzer sinken auf ~Convex-Speicher/Compute ≈ nahe null. Löst zugleich das Haftungsthema (Keys = Verantwortung des Kunden). Ideal für die technik-affine Webdesigner-Zielgruppe.
+2. **Managed (Aufpreis-Modell):** PitchFast nutzt eigene Keys und trägt die API-Kosten; der Preis muss sie mit gesunder Marge decken. Für nicht-technische Nutzer.
+3. **Hybrid:** Software/Seat fix, teure Aktionen (Audits) ziehen aus einem konservativ dimensionierten Kontingent.
+
+### 4.3 SaaS-Abo — primäres Geschäftsmodell (empfohlen)
+
+Beim monatlichen Abo deckt die wiederkehrende Einnahme die variablen Kosten **jeden Monat erneut**. Es gibt also kein „einmal zahlen, ewig kosten"-Problem — und selbst der Managed-Modus ist tragfähig. Konkrete Tiers (marktplausibel, Boutique-Positionierung):
+
+| Tier (mtl.) | Kontingent/Monat | Sitze | Managed-Marge (Voll / realist.) | BYO-Marge | ARR |
+|---|---|---|---|---|---|
+| **Starter** $29 (≈€27) | 30 Audits, 150 Leads | 1 | 82 % / 93 % | 98 % | $348 |
+| **Pro** $79 (≈€73) | 100 Audits, 500 Leads | 2 | 79 % / 93 % | 99 % | $948 |
+| **Agency** $199 (≈€183) | 300 Audits, 1.500 Leads | 5 | 76 % / 93 % | 100 % | $2.388 |
+
+Lesart: „Voll" = Kunde schöpft das Monatskontingent komplett aus (Worst Case für die Marge); „realist." = ~30 % Auslastung. Selbst im Worst Case bleibt die Managed-Bruttomarge **≥ 75 %**; BYO liegt auf Software-Niveau (~98–100 %).
+
+**Mindestpreis-Regel:** `Mindestpreis = COGS bei Vollnutzung ÷ (1 − Ziel-Marge)`. Bei 75 % Ziel-Marge ergibt das pro Tier $21 / $66 / $193 als Preisboden — kein Tier darf darunter liegen. „Unlimited"-Tarife sind ausgeschlossen, weil sie die Vollnutzungs-Marge aushebeln.
+
+**Empfehlung:** BYO-Keys als Default (höchste Marge, keine Kostenkopplung, beste Rechtsposition); Managed als bequemer, höherpreisiger Aufpreis-Tarif für nicht-technische Kunden. Jahreszahlung mit Rabatt anbieten.
+
+### 4.4 Lifetime-Deal / AppSumo (optional, sekundär)
+
+Ein LTD bleibt eine *Option* für einen Reichweiten-Push, ist dem Abo aber wirtschaftlich klar unterlegen und nur unter Auflagen vertretbar. Durchgerechnet (24 Monate Lebensdauer, 30 % Auslastung, 30 % AppSumo-Cut):
+
+| Tier (einmalig) | Netto nach Cut | Managed-Lifetime-P&L | BYO-Lifetime-P&L |
+|---|---|---|---|
+| Tier 1 ($69) | $48 | **−$78** | **+$36** |
+| Tier 2 ($129) | $90 | **−$265** | **+$78** |
+| Tier 3 ($199) | $139 | **−$1.016** | **+$127** |
+
+→ **Managed-LTD ist in jedem Tier strukturell defizitär** (bei Vollnutzung katastrophal, Tier 3: −$3.683). Falls überhaupt LTD, dann **ausschließlich BYO-Keys mit konservativen, nicht-rollierenden Kontingenten**. Zum Vergleich: Schon das günstigste Abo bringt im ersten Jahr ($348) mehr ein, als ein LTD Tier-1 je einbringt.
+
+> Das vollständige, anpassbare Rechenmodell (Annahmen, Stückkosten, Abo- und LTD-Tiers) liegt als `PitchFast_Pricing_Modell.xlsx` bei. Alle Annahmen (blau) lassen sich frei drehen; Margen und Mindestpreise rechnen live nach.
+
+---
+
+## 5. Rechtlicher Rahmen und Compliance-by-Design
+
+> **Kein Ersatz für Rechtsberatung.** Vor einem öffentlichen Launch ist eine Prüfung durch einen Fachanwalt für Wettbewerbs-/IT-Recht zwingend. Die folgenden Punkte sind Produktanforderungen, die Risiko reduzieren, nicht es eliminieren.
+
+### 5.1 Zwei getrennte Rechtsregime (beide müssen erfüllt sein)
+- **UWG § 7 (Versandakt / unlautere Belästigung):** E-Mail-Werbung an Unternehmen setzt grundsätzlich vorherige Einwilligung voraus; Telefonwerbung im B2B verlangt mindestens „mutmaßliche Einwilligung". Eine im Impressum veröffentlichte Geschäftsadresse ist **keine** Einwilligung, Werbung zu empfangen. → Das Produkt darf Kaltakquise nicht als rechtlich unbedenklich darstellen.
+- **DSGVO (Datenverarbeitung):** Verarbeitung von Kontaktdaten kann im B2B über berechtigtes Interesse (Art. 6 Abs. 1 f) begründbar sein, erfordert aber Transparenz, Zweckbindung, Datenminimierung, dokumentierte Interessenabwägung und Wahrung der Betroffenenrechte.
+
+### 5.2 Rolle von PitchFast als Anbieter
+Sobald andere Nutzer Drittdaten über das Tool verarbeiten, wird PitchFast voraussichtlich **Auftragsverarbeiter** (teils evtl. gemeinsam Verantwortlicher). Daraus folgt:
+- **AVV/DPA** mit jedem Kunden (Vertragsvorlage als Onboarding-Schritt).
+- Eigenes Verarbeitungsverzeichnis, TOMs, Löschkonzept.
+- **BYO-Keys/BYO-Mailbox** schwächt diese Rolle bewusst ab, weil der Kunde die Verarbeitung in eigener Infrastruktur ausführt.
+
+### 5.3 Compliance-Features (Pflicht im MVP)
+- **Keine erratenen/generierten E-Mail-Adressen.** Nur Adressen, die nachweislich öffentlich als geschäftlicher Kontakt ausgewiesen sind. Quelle wird pro Datensatz gespeichert (URL + Zeitstempel).
+- **Opt-out-Mechanik** in jeder Outreach-Mail (klar, frictionless), plus interne Suppression-Liste, die einen Opt-out dauerhaft respektiert.
+- **Pflicht-Absenderblock** (Name, ladungsfähige Anschrift, Impressumslink) automatisch in jede Mail.
+- **Quellen-/Begründungsfeld** je Lead: Rechtsgrundlage und Herkunft dokumentiert (Nachweis der Interessenabwägung).
+- **Blacklist** (Domain, E-Mail, Telefon, Firmenname, Place ID) und **Sperrfristen** („Nicht erneut kontaktieren" = 12 Monate hart, danach nur Vorschlag zur manuellen Prüfung).
+- **Betroffenenrechte:** Lösch-/Auskunftsworkflow für angefragte Drittdaten.
+- **Audit-Seiten:** `noindex`, keine Sitemap, kein öffentliches Verzeichnis, Lifecycle-Deaktivierung (30-Tage-Hinweis, 60-Tage-Deaktivierung).
+
+### 5.4 Markt-Regel-Engine
+Eine konfigurierbare `MarketConfig` kapselt pro Land: erlaubte Kontaktkanäle, Consent-Modell (opt-in/opt-out/presumed), Opt-out-Frist, Pflicht-Footer-Felder, Sperrfristen. DE ist die erste Konfiguration; weitere Märkte erst nach eigener Rechtsprüfung.
+
+---
+
+## 6. MVP-Scope und Core User Stories
+
+### 6.1 Mandanten & Konten
+- Als Nutzer möchte ich mich registrieren/einloggen und arbeite in einer isolierten Organisation; ich sehe ausschließlich meine eigenen Daten.
+- Als Org-Inhaber möchte ich (perspektivisch) weitere Sitze einladen — im MVP genügt 1 Nutzer pro Org.
+- Als Nutzer möchte ich meine eigenen API-Keys (Google, OpenRouter, ScreenshotOne) sicher hinterlegen (BYO-Modus) oder Managed-Credits nutzen.
+
+### 6.2 Kampagnen
+- Kampagne anlegen mit Kategorie/Nische (Dropdown + „Anderes"-Freitext), PLZ, Umkreis, Wiederholungsrhythmus, max. neue Leads/Lauf, max. Audits/Lauf.
+- Geocoding der PLZ für die Radius-Suche; Berücksichtigung des 50-km-Radius-Limits und des 60-Ergebnis-Caps (automatische Subdivision bei größerem Gebiet).
+- Wiederkehrende Ausführung per Cron + manueller „Jetzt ausführen"-Trigger.
+
+### 6.3 Lead-Recherche & Qualifizierung
+- Lokale Businesses über Google Places finden (kein Browser-Scraping).
+- Priorisierung nach Website-Potenzial: keine Website, veraltet, schwache Mobile-Darstellung, schwache Kontaktführung, lokale SEO-Chancen; moderne Seiten = niedrige Priorität.
+- Google-Bewertungen intern zur Priorisierung nutzen, extern nie anzeigen.
+- Dublettenschutz + Schutz bereits kontaktierter Firmen + Blacklist-Abgleich.
+- Leads ohne E-Mail in „Kontakt fehlt" sammeln statt verwerfen; bei Telefonnummer Skript zur manuellen Klärung erzeugen.
+
+### 6.4 Website-Audit (serverlose Pipeline)
+- Startseite + relevante Unterseiten (Kontakt, Impressum, Leistungen, Über uns) analysieren.
+- Desktop- + Mobile-Screenshots erfassen und speichern.
+- PageSpeed intern nutzen, extern keine Scores zeigen.
+- Multimodales LLM bezieht Screenshots ein; lokale Design-/Marketing-Skills aus `skills.md`-Registry.
+- Rohdaten (Prompts, Modellname, Rohantworten, Zwischenergebnisse) intern nachvollziehbar speichern.
+
+### 6.5 Öffentliche Audit-Seiten
+- Personalisierte Seite unter `audit.pitchfast.io/<org-slug>/<firmenname-ort>`.
+- Default Entwurfsmodus; extern Hinweis „Dieser Audit ist noch nicht freigegeben", bis manuell freigegeben.
+- `noindex`, Cache + Invalidierung bei Änderung; 30-/60-Tage-Lifecycle mit manueller Reaktivierung.
+
+### 6.6 Outreach (BYO-Mailbox)
+- Kontaktstrategie pro Lead: erst anrufen / direkt E-Mail / zurückstellen / nicht kontaktieren.
+- Review-Workspace: E-Mail-Entwurf, Betreff, Audit-Link, Telefon-Skript — alles editierbar.
+- Versand **aus dem eigenen verbundenen Postfach des Nutzers** (OAuth Gmail/Microsoft oder SMTP), erst nach Freigabe. Kein zentraler Versand.
+- Respektvolles Follow-up vorbereitbar, ebenfalls nur nach Freigabe.
+- Eingehende Antworten im MVP manuell markieren.
+
+### 6.7 Dashboard
+- Kanban/Funnel für Leads & Status.
+- Kampagnenmetriken: Leads, Audits, gesendete Mails, Antworten, Gespräche, Angebote, Aufträge.
+- Rybbit-Daten der eigenen Audit-Seiten im Dashboard (per API), ohne Rybbit separat zu öffnen.
+- Credit-/Nutzungsanzeige + Fehlerstatus je externem Dienst.
+
+### 6.8 Abrechnung & Lizenz
+- Credit-Verbrauch messen (pro Audit/Lead), Kontingente durchsetzen.
+- Abo-Verwaltung (Stripe) und/oder AppSumo-Code-Einlösung per Webhook (falls LTD-Launch).
+
+---
+
+## 7. Out of Scope (MVP)
+- Mehr als 1 aktiver Nutzer pro Organisation (Datenmodell aber bereits multi-tenant).
+- Automatische Inbox-/Antwort-Auswertung (JMAP-Threading).
+- Vollwertiges CRM, Call-Queue mit Gesprächsnotizen.
+- Automatischer Versand ohne manuelle Freigabe.
+- Google-Maps-Scraping per Browser-Automation.
+- Internationale Märkte außerhalb Deutschlands (Engine vorbereitet, Konfiguration nicht).
+- Externes Error-Monitoring (Sentry) — optional später.
+- Mehr als ein gleichzeitiger Agentenlauf pro Organisation.
+
+---
+
+## 8. Technische Architektur und Tech-Stack
+
+### 8.1 Übersicht
+```
+  Next.js (App Router) ──▶ Cloudflare Pages (Edge)
+            │  WebSockets (reaktiv)
+            ▼
+       CONVEX CLOUD  ── DB (multi-tenant) · File Storage · Crons · Actions
+            │  triggert externe serverlose Dienste / Worker
+            ▼
+  ┌─────────────┬───────────────┬───────────────┬──────────────┐
+  │ Google      │ Jina AI       │ ScreenshotOne │ OpenRouter    │
+  │ Places/Geo/ │ (Markdown)    │ (Screenshots) │ (GPT-5.4 mini)│
+  │ PageSpeed   │               │               │               │
+  └─────────────┴───────────────┴───────────────┴──────────────┘
+  Transaktionsmail: Resend   ·   Outreach-Versand: BYO-Mailbox (OAuth/SMTP)
+  Analytics: Rybbit (self-hosted, nur Audit-Seiten)
+```
+
+### 8.2 Komponenten
+- **Frontend/Edge:** Next.js App Router, shadcn/ui, Tailwind, React Hook Form + Zod. Dashboard mit Light/Dark Mode; öffentliche Audit-Seiten fest hell/ruhig.
+  - ⚠️ *Entscheidung offen:* Next.js App Router auf Cloudflare Pages hat Reibung (OpenNext/`next-on-pages`, Edge-Runtime-Eigenheiten). Vercel ist der Weg des geringsten Widerstands, Cloudflare billiger bei Skalierung. → In Abschnitt 19 zu entscheiden.
+- **Backend/Daten:** Convex Cloud. **Jedes Dokument trägt `orgId` (Pflicht); jede Query filtert nach `orgId`.** File Storage für Screenshots. Crons/Actions für Kampagnenläufe, Audit-Pipeline, Lifecycle-Regeln.
+- **Auth:** Better Auth mit Convex; E-Mail/Passwort, Organisations-Scoping. Öffentliche Audit-Seiten ohne Login.
+- **Agenten-/LLM-Schicht:** Vercel AI SDK als Orchestrierung, OpenRouter als Modellzugang, GPT-5.4 mini (Text+Vision), strukturierte Outputs via Zod. Modellprofile für Lead-Klassifikation, Audit-Analyse, multimodale Analyse, Textgenerierung, Qualitätscheck. `skills.md`-Registry (Name, Zweck, Einsatzbereich, Input, Output) im Repo; Dashboard zeigt pro Audit die verwendeten Skills.
+- **Recherche/Analyse:** Google Geocoding + Places + PageSpeed Insights; Cheerio (schneller HTML-/SEO-First-Pass auf der Edge); Jina AI Reader (HTML→Markdown); ScreenshotOne (Desktop/Mobile, Cookie-/Pop-up-Filter). RapidAPI nur als optionaler Fallback.
+- **Mail:** **Resend** für transaktionale Mails (App-Benachrichtigungen, „Audit fertig", Passwort-Reset). **BYO-Mailbox** für Outreach (Gmail/Microsoft via OAuth oder Kunden-SMTP). Kein gemeinsamer Outreach-Versand → schützt Reputation und Rechtsposition. (Stalwart entfällt als zentrale Komponente; Matthias kann sein eigenes Stalwart-Postfach im BYO-Modus verbinden.)
+- **Analytics:** Rybbit (self-hosted), nur auf öffentlichen Audit-Seiten, anonym; Aggregation per API im Dashboard.
+- **Deployment/Config:** Coolify oder Cloudflare (siehe offene Entscheidung). Secrets in Convex Secrets / Env; **Kunden-API-Keys verschlüsselt at rest, nie im Klartext im UI/Repo/Log**.
+
+### 8.3 Kostenkontrolle (eingebaut)
+- Harte Limits pro Kampagne (Leads/Audits pro Lauf).
+- Nur ein aktiver Agentenlauf pro Org gleichzeitig.
+- **Globaler Monats-Budget-Cap + Kill-Switch** je Org (greift auch im Managed-Modus).
+- Kosten-Logging pro Lauf (Token-, Call-Zahlen) für reale Unit-Economics-Messung.
+
+---
+
+## 9. Konzeptionelles Datenmodell (multi-tenant)
+
+> Jede Entität trägt `orgId` und (wo sinnvoll) `createdBy`. Alle Queries scopen auf `orgId`.
+
+**Organization** — id, name, slug, plan, status, marketConfigId, createdAt
+**User** — id, orgId, email, role, authRef
+**ApiKeyVault** — orgId, provider (google/openrouter/screenshotone), encryptedKey, mode (byo/managed), status
+**Subscription / CreditLedger** — orgId, plan, creditBalance, monthlyAllowance, allowanceResetAt, appsumoLicenseId?
+**UsageEvent** — orgId, type (audit/lead_lookup), costEstimate, tokensIn/Out, callCounts, createdAt *(für Abrechnung + Unit-Economics)*
+**MailboxConnection** — orgId, provider (gmail/microsoft/smtp), oauthRef/smtpConfig (encrypted), fromName, fromAddress, status
+**MarketConfig** — id, country, consentModel, allowedChannels, optOutDeadlineDays, requiredFooterFields, suppressionMonths
+**Campaign** — orgId, name, niche/freitext, plz, ort, coordinates, radius, schedule, maxLeadsPerRun, maxAuditsPerRun, status, lastRun, nextRun
+**Lead** — orgId, campaignId, companyName, niche, address, googlePlaceId, source, domain, phone, email, emailSource (url+ts), contactPerson, priority, contactStatus, duplicateStatus, blocklistStatus, legalBasisNote, internalNotes
+**Audit** — orgId, leadId, status (draft/approved/published/expired), slug, checkedDomain, checkedSubpages, screenshots[], pageSpeedRaw, cheerioFindings, jinaMarkdown, foundTextSnippets, usedSkills[], skillOutputs, multimodalAnalysis, finalSummary, publicAuditText, ctaType, publishedAt, noticeSentAt (30d), deactivatedAt (60d)
+**Outreach** — orgId, leadId, auditId, contactStrategy, phoneScript, emailSubject, emailBody, followUpBody, approvalStatus, sentAt, mailboxConnectionId, replyStatus, salesStatus *(Follow-up geplant/gesendet, Antwort erhalten, Kein Interesse, Später, Gespräch vereinbart, Angebot angefragt/gesendet, Auftrag gewonnen/verloren, Nicht weiter verfolgen)*
+**Suppression / OptOut** — orgId, value (email/domain), reason, createdAt *(dauerhaft respektiert)*
+**Blacklist** — orgId, type (domain/email/phone/company/placeId), value, note, createdAt
+**RunLog** — orgId, campaignId, status, errorByService (google/pagespeed/openrouter/screenshotone/jina/mail), startedAt, finishedAt
+
+> **Google-Places-ToS-Hinweis:** Nur die `googlePlaceId` darf dauerhaft gespeichert werden; übrige Places-Felder unterliegen Caching-Beschränkungen (i. d. R. ~30 Tage) und müssen ggf. per ID-Refresh erneuert werden. Datenhaltung entsprechend gestalten.
+
+---
+
+## 10. Audit-Pipeline im Detail
+
+Asynchroner Job, nicht synchroner Request (kein hartes 30-Sek-SLA — siehe Erfolgskriterien). Ablauf je Lead:
+
+1. **Struktur-Check (Cheerio):** Roh-HTML parsen → Meta/Title/Headings/Viewport/strukturelle SEO-Signale. Billiger First-Pass.
+2. **Copy-Extraktion (Jina):** Startseite + relevante Unterseiten → sauberes Markdown.
+3. **Visuelle Erfassung (ScreenshotOne):** Desktop + Mobile, Cookie-/Pop-up-Filter. *Reliability-Hinweis:* ScreenshotOne hat in Benchmarks bei komplexen Seiten Ausfälle gezeigt — Fallback/Retry vorsehen, ggf. Alternativ-Provider (Urlbox o. ä.) für schwierige Seiten evaluieren. ScreenshotOne berechnet fehlgeschlagene Requests nicht.
+4. **PageSpeed:** technische Performance-/Accessibility-Signale (intern).
+5. **KI-Auswertung (GPT-5.4 mini):** Markdown + technische Signale + Screenshots (Vision) + `skills.md` → strukturierter Output (Zod): interne Befunde, öffentlicher Audit-Text, Mail-Entwurf, Betreff, Telefon-Skript, CTA-Typ.
+6. **Qualitäts-Gate:** Anti-KI-Slop-Check (zweiter, billiger Modell-Pass oder Heuristiken) gegen Voice-Regeln.
+7. **Persistenz:** Rohdaten + finale Texte in Convex; Job-Status reaktiv ans Dashboard; „fertig"-Notification via Resend.
+
+Fehler je Stufe werden im `RunLog` sichtbar gemacht; der Lauf bricht sauber ab oder überspringt einzelne Leads nachvollziehbar.
+
+---
+
+## 11. UI/UX-Prinzipien und Accessibility
+- Dashboard = funktionales Arbeitswerkzeug: dicht, scanbar, effizient, keine Marketing-Optik. Hauptansicht Kanban/Funnel. Review-Ansicht bündelt Lead-Daten, Audit, Mail, Betreff, Skript, Quellen, Freigabeaktionen.
+- Öffentliche Audit-Seite: ruhiger als eine Marketing-Seite, persönlich, beratend, respektvoll. Keine Scores, Ampeln, Warnfarben, anklagende Sprache. Screenshots ohne Annotationen im Kontext der Befunde. Angebot + Link zur Hauptsite am Ende.
+- Vollständige Tastaturbedienbarkeit, klare Labels/Fehlermeldungen, valide Kontraste, kein Textüberlauf auf Mobile/Desktop.
+- Deutsche UI, für i18n vorbereitet.
+
+---
+
+## 12. Voice & Tone
+Alle Mails/Audit-Texte in Ich-Form (Solo-Freelancer-Perspektive bzw. die des jeweiligen Nutzers). Stil: auf Augenhöhe, konkret, lokal/nahbar, respektvoll, nicht belehrend, frei von KI-Floskeln, ohne übertriebene Dringlichkeit, ohne Preise in der Erstansprache. Der Agent formuliert Beobachtungen und Vorschläge, keine Urteile; technische Befunde werden in Kundennutzen übersetzt (weniger Absprünge, bessere mobile Kontaktaufnahme, mehr Vertrauen, bessere lokale Auffindbarkeit).
+
+---
+
+## 13. Nicht-funktionale Anforderungen
+- Mandantenisolation ist Pflichtinvariante (Tests dafür).
+- Qualität vor Menge; kleine, harte Lead-/Audit-Limits.
+- Ein aktiver Agentenlauf pro Org; Läufe abbrechbar oder nachvollziehbar fehlschlagend.
+- Fehlerstatus je externem Dienst im Dashboard sichtbar.
+- Öffentliche Audit-Seiten laden schnell, werden gecached, Invalidierung bei Änderung.
+- Audit-Rohdaten intern nachvollziehbar.
+- Globaler Budget-Cap + Kill-Switch je Org.
+- DSGVO-Löschworkflow funktionsfähig.
+
+---
+
+## 14. Sicherheit, Mandantenisolation & Secrets
+- `orgId`-Scoping in jeder Query; serverseitige Autorisierung, nie nur clientseitig.
+- Kunden-API-Keys und SMTP-/OAuth-Credentials **verschlüsselt at rest**; nie im UI rückanzeigbar, nie in Logs.
+- Plattform-Secrets in Convex Secrets / Env, nicht im Repo.
+- Rate-Limiting/Abuse-Schutz pro Org (verhindert, dass ein Nutzer Kosten/Reputation anderer beeinflusst — im BYO-Modus ohnehin entkoppelt).
+- Öffentliche Audit-Seiten: `noindex`, keine Sitemap, kein Verzeichnis, Slugs nicht erratbar (Hash-Anteil).
+
+---
+
+## 15. Entwicklungsphasen und Meilensteine
+
+**M1 — Foundation & Multi-Tenancy:** Next.js-Dashboard-Gerüst, Convex Cloud, Better Auth mit Org-Scoping, `orgId` auf allen Modellen, Kampagnen-/Lead-Datenmodell, Basis-Kanban, ApiKeyVault (BYO-Keys-Eingabe, verschlüsselt).
+**M2 — Recherche & Qualifizierung:** Geocoding, Places-Suche (mit Subdivision/Field-Mask-Kostenkontrolle), Kategorien + „Anderes", Dublettenprüfung, „Kontakt-fehlt", Blacklist, Quellen-/Rechtsgrundlagen-Feld.
+**M3 — Audit-Pipeline:** Cheerio, Jina, ScreenshotOne, PageSpeed, `skills.md`, GPT-5.4-mini-Analyse (Vision), Rohdatenhaltung, async Job + RunLog.
+**M4 — Audit-Seiten & Review:** öffentliche Seite, manuelle Freigabe, `noindex`/Cache, 30-/60-Tage-Lifecycle, Review-Workspace.
+**M5 — Outreach (BYO-Mailbox) & Follow-up:** Mailbox-Connect (OAuth/SMTP), Mail-/Betreff-/Skript-Entwurf, Versand nach Freigabe, Follow-up, Suppression/Opt-out, manuelles Antwort-/Sales-Tracking, Pflicht-Footer.
+**M6 — Abrechnung & Lizenz:** Credit-Metering, Kontingent-Durchsetzung, Budget-Cap/Kill-Switch, Stripe-Abo und/oder AppSumo-Webhook.
+**M7 — Analytics & Compliance-Härtung:** Rybbit auf Audit-Seiten + API im Dashboard, Kampagnenmetriken, Anti-KI-Slop-Regeln, AVV-Vorlage + DSGVO-Löschworkflow, UI-/Accessibility-Review, Fachanwalt-Review vor Launch.
+
+---
+
+## 16. Technische Herausforderungen & Mitigation
+- **API-Kosten/Limits:** BYO-Keys verlagern variable Kosten; harte Limits + Budget-Cap; Field-Mask-Disziplin bei Places (Contact-Data nur wenn nötig).
+- **Schlechte/fehlende Kontaktdaten:** „Kontakt fehlt" + Telefon-Skript; keine geratenen Adressen.
+- **Generische KI-Texte:** konkrete Website-Daten + Screenshots + Skills + Voice-Regeln + Qualitäts-Gate + manuelle Bearbeitung.
+- **Fehlerhafte visuelle Interpretation:** multimodale Befunde mit DOM/Text/PageSpeed kreuzvalidieren; extern nur vorsichtig formulierte Beobachtungen.
+- **Screenshot-Zuverlässigkeit:** Retry/Fallback-Provider, da Benchmarks Ausfälle bei komplexen Seiten zeigen.
+- **Rechtliche Sensibilität:** keine Automatik, Quellenhaltung, manuelle Freigabe, zurückhaltende Sprache, Sperrfristen, BYO-Postfach, AVV, Fachanwalt vor Launch.
+- **Mandanten-Datenlecks:** `orgId`-Invariante + Tests; verschlüsselte Secrets.
+- **Next-auf-Cloudflare-Reibung:** früh ein Spike-Deployment, sonst Vercel.
+- **LTD-Unwirtschaftlichkeit:** BYO-Keys-Default; Managed nur mit ≥2× Marge und nicht-rollierenden Kontingenten.
+
+---
+
+## 17. Erfolgskriterien für das MVP (überarbeitet, realistisch)
+1. Matthias kann wiederkehrende lokale Kampagnen anlegen, ausführen und qualitativ passende Leads mit nachvollziehbaren Quellen erhalten.
+2. Der Agent erstellt brauchbare Mini-Audits (Screenshots, PageSpeed-Kontext, konkrete Vorschläge); öffentliche Audit-Seiten wirken persönlich, ruhig, nicht anklagend.
+3. **Reale Stückkosten gemessen und transparent:** Ziel-Korridor ~$0,05–0,08 pro „Lead + Audit" (nicht die alten $0,02); jeder Lauf loggt tatsächliche Kosten.
+4. Mail/Betreff/Skript editierbar; **kein Versand ohne `approved`-Status**; Versand läuft über das verbundene Postfach des Nutzers.
+5. Mandantenisolation nachweislich dicht (mind. 1 Test, der Cross-Org-Zugriff verhindert).
+6. Compliance-Features funktionsfähig: Quellen-Doku, Opt-out + Suppression, Pflicht-Footer, Sperrfristen, Löschworkflow.
+7. Unit-Economics-Modell bestätigt: Im gewählten Preis-/BYO-Modell ist ein aktiver Nutzer nicht strukturell defizitär.
+8. Kampagnenmetriken + Rybbit-Daten geben schnellen Überblick über Wirkung und Fortschritt.
+
+---
+
+## 18. Zukünftige Erweiterungen
+Mehrere Sitze/Teamrollen · zusätzliche Märkte (je mit eigener `MarketConfig` + Rechtsprüfung) · automatische Inbox-/Thread-Zuordnung (JMAP) · vollwertiges CRM · Call-Queue mit Notizen · automatisierte Re-Audits · erweiterte Rybbit-/Conversion-Auswertung · alternative Screenshot-/Scrape-Provider · zusätzliche Sprachen · self-hosted Convex für Enterprise.
+
+---
+
+## 19. Offene Entscheidungen & verwendete Annahmen
+
+**Zu entscheiden:**
+1. **Hosting:** Cloudflare Pages (billiger, mehr Reibung mit Next App Router) vs. Vercel (reibungslos, teurer). → Spike empfohlen.
+2. **Preismodell:** SaaS-Abo ist gesetzt (Tiers/Margen siehe 4.3). Offen: finale Preispunkte & Kontingente, Ziel-Bruttomarge, ob ein BYO-LTD als sekundärer Reichweiten-Kanal überhaupt aufgelegt wird.
+3. **BYO vs. Managed als Default** für die erste Zielgruppe (Empfehlung: BYO; Managed als Aufpreis-Tarif).
+4. **Screenshot-Provider** final: ScreenshotOne vs. Alternative nach Reliability-Test.
+5. **Fachanwalt-Mandat** vor Launch terminieren (UWG/DSGVO/AVV).
+
+**Verwendete Annahmen (Unit Economics, vor Launch verifizieren):**
+- GPT-5.4 mini: $0,75/M Input, $4,50/M Output (OpenRouter, Mitte 2026).
+- ScreenshotOne: ~$0,0085/Screenshot.
+- Google Places: Pro-SKUs Nearby/Text Search ~$0,032/Call, Place Details ~$0,017/Call, Contact-Data-SKU ~$0,003/Call; SKU-/Field-Mask-basiert; begrenzte monatliche Free-Caps.
+- AppSumo-Umsatzbeteiligung: ~30 % (Planungswert).
+- FX: EUR ≈ USD × 0,92.