pounce/UNICORN_PLAN.md

## Pounce Unicorn Plan (integriert)

Ziel: Pounce von einem starken Produkt (Trust + Inventory + Lead Capture) zu einem skalierbaren System mit Moat + Flywheel entwickeln.

---

## Umsetzungsstatus (Stand: 2025-12-15)

### Wo wir stehen (kurz, ehrlich)

- **Deal-System (Liquidity Loop)**: **fertig & gehärtet** (Inbox → Threading → Sold/GMV → Anti‑Abuse).
- **Yield (Moat)**: **Connect + Routing + Tracking + Webhooks + Ledger-Basis** ist da. Wir können Domains verbinden, Traffic routen, Clicks/Conversions tracken und Payouts vorbereiten/abschliessen.
- **Flywheel/Distribution**: teilweise (Public Deal Surface + Login Gate ist da), Programmatic SEO & Viral Loop noch nicht systematisch ausgebaut.
- **Telemetry/Ops**: einzelne Events existieren implizit (Audit/Transactions), aber **kein zentrales Event-Schema + KPIs Dashboard**.

### Fortschritt nach Workstream

#### 1) Deal‑System
- [x] 1A Inbox Workflow (Status, Close Reason, Audit)
- [x] 1B Threading/Negotiation (Buyer/Seller Threads + Email + Rate Limits + Content Safety)
- [x] 1C Deal Closure + GMV (Mark as Sold, Close open inquiries)
- [x] 1D Anti‑Abuse (Limits + Safety Checks an den kritischen Stellen)

#### 2) Yield (Moat)
- [x] 2A Connect/Nameserver Flow (Portfolio‑Only + DNS Verified + Connect Wizard + `connected_at`)
- [x] 2B Routing → Tracking (Async, Click Tracking, IP‑Hashing, Rate‑Limit, strict partner config)
- [x] 2B Attribution (Webhook kann `click_id` mitschicken)
- [x] 2C Ledger/Payout‑Basics (generate payouts + complete payouts; server‑safe keys)
- [x] 2C.2 Dashboard‑Korrektheit (monatliche Stats = confirmed/paid, pending payout = confirmed+unpaid)

#### 3) Flywheel / Distribution
- [~] 3B Public Deal Surface + Login Gate (Pounce Direct gated) — **vorhanden**
- [~] 3A Programmatic SEO maximal (Templates + CTA Pfade + Indexation)
- [~] 3C Viral Loop „Powered by Pounce“ (nur wo intent passt, sauberer Referral Loop)

**3C Stand (Viral Loop)**
- **Invite Codes**: jeder User hat jetzt einen eigenen `invite_code` (unique) + `GET /api/v1/auth/referral` liefert den Invite‑Link.
- **Attribution**: `ref` wird auf Public Pages in Cookie gespeichert (30 Tage) und bei `/register` mitgeschickt → Backend setzt `referred_by_user_id`.
- **Surfaces (intent-fit)**:
  - Terminal Settings: “Invite” Panel mit Copy‑Link
  - Public Buy Listing: “Powered by Pounce” → Register mit `?ref=<seller_invite_code>`
- **Telemetry**: Events `user_registered`, `referral_attributed`, `referral_link_viewed`
- **Admin KPIs (3C.2)**: Telemetry Tab zeigt jetzt Referral‑KPIs (Link Views + Signups pro Referrer) via `GET /api/v1/telemetry/referrals?days=...`
- **Rewards/Badges (3C.2)**: Deterministische Referral‑Rewards (abuse‑resistent) → `subscriptions.referral_bonus_domains` (+5 Slots pro 3 “qualified referrals”), Badge `verified_referrer` / `elite_referrer` wird im Terminal‑Settings Invite‑Panel angezeigt.
  - **Anti‑Fraud/Cooldown**: Qualified zählt erst nach **Cooldown** (User+Subscription Age) und wird bei **shared IP / duplicate IP / missing IP** disqualifiziert (Telemetry `ip_hash`).

**3A Stand (Programmatic SEO)**
- **Indexation**: `sitemap.xml` ist jetzt dynamisch (Discover‑TLDs aus DB + Blog Slugs + Public Listings) und `robots.txt` blockt Legacy Pfade.
- **Canonical Cleanup**: Legacy Routen (`/tld/*`, `/tld-pricing/*`) redirecten server-seitig nach `/discover/*`.
- **Templates**: `/discover/[tld]` hat jetzt server‑seitiges Metadata + JSON‑LD (aus echten Registrar‑Compare Daten). `/buy/[slug]` ist server‑seitig (Metadata + JSON‑LD).
- **Blog Article SEO**: `/blog/[slug]` hat jetzt server‑seitiges `generateMetadata` + Article JSON‑LD, ohne View‑Count Side‑Effects (Meta‑Endpoint).

#### 4) Skalierung / Telemetry
- [x] 4A Events (kanonisches Event-Schema + persistente Events in Deal+Yield Funnel)
- [x] 4A.2 KPI Views (Admin KPIs aus Telemetry Events: Rates + Median Times)
- [x] 4B Ops (Backups + Restore-Verification + Monitoring/Alerts + Deliverability)

**4B Stand (Ops)**
- **Backups**: Admin-Endpoint + Scheduler Daily Backup + Restore-Verification (SQLite integrity_check / Postgres pg_restore --list)
- **Monitoring**: `/metrics` exportiert jetzt zusätzlich Business-KPIs (Deal+Yield aus `telemetry_events`, gecached) + Ops-Metriken (Backup enabled + Backup age)
- **Deliverability**: Newsletter Emails mit `List-Unsubscribe` (One-Click) + neue One-Click Unsubscribe Route
- **Alerting (Vorbereitung)**: `ops/prometheus-alerts.yml` mit Alerts (5xx rate, Backup stale, 24h Funnel-Null)
- **Alerting (ohne Docker)**: Scheduler Job `ops_alerting` + Admin Endpoint `POST /api/v1/admin/system/ops-alerts/run`
- **Alert History + Cooldown (persistiert)**: Table `ops_alert_events` + Admin Endpoint `GET /api/v1/admin/system/ops-alerts/history` + Admin UI History Panel

---

## Absicht & holistisches Konzept

### Absicht (warum es Pounce gibt)

Pounce existiert, um Domains von „toten Namen“ (nur Renewal-Kosten, keine Nutzung) zu **messbaren, handelbaren digitalen Assets** zu machen.  
Wir bauen nicht nur einen Feed oder einen Marktplatz, sondern eine **Lifecycle Engine**: entdecken → erwerben → monetarisieren → liquidieren.

### Für wen (Zielgruppe)

- **Domain Investors / Operators**: brauchen sauberes Inventory, schnelle Entscheidungen, klare Workflows.
- **Builders / Entrepreneurs**: wollen gute Assets finden und sofort nutzen/monetarisieren.
- **Portfolio Owner** (ab 10+ Domains): wollen Governance (Health, Renewal, Cashflow) statt Chaos.

### Positionierung (klarer Satz)

**Pounce ist das Operating System für Domains**: ein Clean Market Feed + Verified Direct Deals + Yield Routing – mit Messbarkeit vom ersten View bis zum Exit.

### Das Gesamtmodell (4 Module)

1. **Discover (Intelligence)**
   Findet Assets: Clean Feed, Scores, TLD Intel, Filter, Alerts.

2. **Acquire (Marketplace / Liquidity)**
   Sichert Assets: externe Auktionen + **Pounce Direct** (DNS-verified Owner).

3. **Yield (Intent Routing)**
   Monetarisiert Assets: Domain-Traffic → Intent → Partner → Revenue Share.

4. **Trade (Exit / Outcomes)**
   Liquidität und Bewertung: Domains werden nach **Cashflow** bepreist (Multiple), nicht nur nach „Vibe“.

### Warum das Unicorn-Potenzial hat (Moat + Flywheel)

- **Moat**: Proprietäre Daten über Intent, Traffic, Conversion und Cashflow auf Domain-Level (schwer kopierbar).
- **Flywheel**: mehr Domains → mehr Routing/Conversions → mehr Daten → bessere Scores/Routing → mehr Deals → mehr Domains.

---

## 0) Leitprinzipien

- **Moat entsteht dort, wo proprietäre Daten entstehen**: Yield/Intent + Deal Outcomes.
- **Trust ist ein Feature**: alles, was Spam/Scam senkt, steigert Conversion.
- **Telemetry ist nicht „später“**: jede neue Funktion erzeugt Events + messbare KPIs.

---

## 1) Deal‑System (Liquidity Loop fertig machen)

### 1A — Inbox Workflow (Woche 1)

**Ziel**: Seller können Leads zuverlässig triagieren und messen.

- **Inquiry Status Workflow komplett**: `new → read → replied → closed` + `spam`
  - Backend PATCH Endpoint + UI Actions
  - „Close“ inkl. Grund (z.B. sold elsewhere / low offer / no fit)
- **Audit Trail (minimal)**
  - jede Statusänderung speichert: `who/when/old/new`

**KPIs**
- inquiry→read rate
- inquiry→replied rate
- median reply time

### 1B — Threading/Negotiation (Woche 2–3)

**Ziel**: Verhandlung im Produkt, nicht off-platform.

- **Threading**: Buyer ↔ Seller Messages als Conversation pro Listing
- **Notifications**: E‑Mail „New message“ + Login‑Gate
- **Audit Trail (voll)**: message events + status events
- **Security**: rate limits (buyer + seller), keyword checks, link safety

**KPIs**
- inquiry→first message
- messages/thread
- reply rate

### 1C — Deal Closure + GMV (Woche 3–4)

**Ziel**: echte Conversion/GMV messbar machen.

- **“Mark as Sold”** auf Listing
  - Gründe: sold on Pounce / sold off‑platform / removed
  - optional: **deal_value** + currency
- optional sauberer **Deal-Record**
  - `deal_id`, `listing_id`, `buyer_user_id(optional)`, `final_price`, `closed_at`

**KPIs**
- inquiry→sold
- close rate
- time-to-close
- GMV

### 1D — Anti‑Abuse (laufend ab Woche 1)

- **Rate limit** pro IP + pro User (inquire + message + status flips)
- **Spam flagging** (Heuristiken + manuell)
- **Blocklist** (buyer account/email/domain-level)

**KPIs**
- spam rate
- blocked attempts
- false positive rate

---

## 2) Yield als Burggraben (Moat)

### 2A — Connect/Nameserver Flow (Woche 2–4)

**Ziel**: Domains „unter Kontrolle“ bringen (Connect Layer).

- **Connect Wizard** (Portfolio → Yield)
  - Anleitung: NS/TXT Setup
  - Status: pending/verified/active
- **Backend checks** (NS/TXT) + Speicherung: `connected_at`
- **Routing Entry** (Edge/Web): Request → route decision

**KPIs**
- connect attempts→verified
- connected domains

### 2B — Intent → Routing → Tracking (Monat 2)

**Ziel**: Intent Routing MVP für 1 Vertical.

- **Intent detection** (MVP)
- **Routing** zu Partnern + Fallbacks
- **Tracking**: click_id, domain_id, partner_id
- **Attribution**: conversion mapping + payout status

**KPIs**
- clicks/domain
- conversion rate
- revenue/domain

### 2C — Payout + Revenue Share (Monat 2–3)

- Ledger: pending → confirmed → paid
- payout schedule (monatlich) + export/reports

**KPIs**
- payout accuracy
- disputes
- net margin

### 2D — Portfolio Cashflow Dashboard (Monat 3)

- Portfolio zeigt: **MRR, last 30d revenue, ROI**, top routes
- Domains werden „yield-bearing assets“ → später handelbar nach Multiple

**KPIs**
- MRR
- retention/churn
- expansion

---

## 3) Flywheel / Distribution

### 3A — Programmatic SEO maximal (Monat 1–2)

- Templates skalieren (TLD/Intel/Price)
- klare CTA‑Pfade: „Track this TLD“, „Enter Terminal“, „View Direct Deals“

**KPIs**
- organic sessions
- signup conversion

### 3B — Public Deal Surface + Login Gate (Monat 1)

- Public Acquire + /buy als Conversion‑Engine
- “contact requires login” überall konsistent

**KPIs**
- view→login
- login→inquiry

### 3C — Viral Loop „Powered by Pounce“ (Monat 2–3)

- nur wenn intent passt / low intent fallback
- referral link + revenue share

**KPIs**
- referral signups
- CAC ~0

---

## 4) Skalierung / Telemetry

### 4A — Events (Woche 1–2)

Definiere & logge Events:
- `listing_view`
- `inquiry_created`
- `inquiry_status_changed`
- `message_sent`
- `listing_marked_sold`
- `yield_connected`
- `yield_click`
- `yield_conversion`
- `payout_paid`

**KPIs**
- funnel conversion
- time metrics

### 4B — Ops (Monat 1)

- Monitoring/alerts (Errors + Business KPIs)
- Backups (DB daily + restore drill)
- Deliverability (SPF/DKIM/DMARC, bounce handling)
- Abuse monitoring dashboards

---

## Empfohlene Reihenfolge (damit es schnell „unfair“ wird)

1. **Deal-System 1A–1C** (GMV & close-rate messbar)
2. **Yield 2A** (Connect Layer) parallel starten
3. **Events 4A** sofort mitziehen
4. **Yield 2B–2C** (Moat) sobald Connect stabil
5. Flywheel 3A–3C kontinuierlich