Files

Matthias Meister e9463e8ef2 Surface audit generations on dashboard audits

2026-06-06 18:14:27 +02:00

31 KiB

Raw Permalink Blame History

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:

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.
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.
Qualität vor Menge. Harte, niedrige Limits pro Lauf. Kein „Unlimited".
Kein Autopilot. Versand niemals ohne manuelle Freigabe — architektonisch erzwungen, nicht nur per Policy.
Compliance als Feature. Quellen-Dokumentation, Opt-out, Impressums-Block, Sperrfristen und AVV sind verkaufbare Funktionen, kein Kleingedrucktes.
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:

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.
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.
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:

Struktur-Check (Cheerio): Roh-HTML parsen → Meta/Title/Headings/Viewport/strukturelle SEO-Signale. Billiger First-Pass.
Copy-Extraktion (Jina): Startseite + relevante Unterseiten → sauberes Markdown.
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.
PageSpeed: technische Performance-/Accessibility-Signale (intern).
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.
Qualitäts-Gate: Anti-KI-Slop-Check (zweiter, billiger Modell-Pass oder Heuristiken) gegen Voice-Regeln.
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)

Matthias kann wiederkehrende lokale Kampagnen anlegen, ausführen und qualitativ passende Leads mit nachvollziehbaren Quellen erhalten.
Der Agent erstellt brauchbare Mini-Audits (Screenshots, PageSpeed-Kontext, konkrete Vorschläge); öffentliche Audit-Seiten wirken persönlich, ruhig, nicht anklagend.
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.
Mail/Betreff/Skript editierbar; kein Versand ohne approved-Status; Versand läuft über das verbundene Postfach des Nutzers.
Mandantenisolation nachweislich dicht (mind. 1 Test, der Cross-Org-Zugriff verhindert).
Compliance-Features funktionsfähig: Quellen-Doku, Opt-out + Suppression, Pflicht-Footer, Sperrfristen, Löschworkflow.
Unit-Economics-Modell bestätigt: Im gewählten Preis-/BYO-Modell ist ein aktiver Nutzer nicht strukturell defizitär.
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:

Hosting: Cloudflare Pages (billiger, mehr Reibung mit Next App Router) vs. Vercel (reibungslos, teurer). → Spike empfohlen.
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.
BYO vs. Managed als Default für die erste Zielgruppe (Empfehlung: BYO; Managed als Aufpreis-Tarif).
Screenshot-Provider final: ScreenshotOne vs. Alternative nach Reliability-Test.
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.

31 KiB Raw Permalink Blame History Unescape Escape