add research folder with market docs, strategy notes, and KfW files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

research/PLAN.md

@@ -0,0 +1,508 @@
+# Padelnomics — Execution Plan
+
+**Date:** 2026-02-16
+**Model:** Zillow for padel — open consumer tool, monetize both sides
+
+---
+
+## Positioning
+
+**One-liner:** The intelligence platform for padel entrepreneurs — plan your facility, get builder quotes, export a bank-ready business plan.
+
+**Business model:** Two-sided marketplace.
+- **Entrepreneur side (padelnomics.io):** Open planner drives traffic and engagement. Revenue from paid business plan export (bank-ready PDF). Later: market intelligence subscriptions.
+- **Builder/supplier side (padelnomics.io/suppliers):** Pay for qualified leads via credits and subscriptions. Boost upsells for directory visibility. All leads paywalled from day one.
+- **Data moat:** Playtomic scraping starts early, compounds daily. Improves planner defaults, powers market research. Eventually becomes its own paid product.
+
+**Languages:** English (default) + German from launch.
+
+**Name:** Padelnomics (final). Keep current branding and colors.
+
+---
+
+## Architecture: Two Audiences, Two Experiences
+
+### padelnomics.io — Entrepreneur Side
+
+Clean, minimal. Calculator front and center.
+
+- Full 6-tab planner works without signup (guest mode)
+- All 60+ variables, all charts, all metrics — zero friction
+- **Signup required for:** saving scenarios, exporting business plan PDF, requesting builder quotes
+- Hero: "Plan. Finance. Build." + calculator entry point
+- Journey stages visible as roadmap with "Coming Soon" badges on future stages
+
+### padelnomics.io/suppliers — Builder/Supplier Side
+
+Separate landing page, separate value prop, separate dashboard.
+
+- Sells lead access to builders/suppliers
+- Shows: lead volume, avg project value, how credits work, pricing tiers
+- Signup flow with plan selection + boost upsells (RemoteOK-style psychology)
+- Dashboard: KPIs, lead feed, listing management, boost toggles
+
+Entrepreneurs never see builder pricing. Builders never see the planner internals.
+
+---
+
+## Product & Pricing Structure (Paddle)
+
+### Entrepreneur Products
+
+| Product | Type | Price | Paddle Config |
+|---------|------|-------|---------------|
+| **Padel Business Plan** | One-time | €99 | One-time charge |
+| **Padel Business Plan Pro** | Subscription | €39/mo | Monthly recurring |
+| *(Phase 3) Market Intelligence Explorer* | Subscription | €79/mo | Monthly recurring |
+| *(Phase 3) Market Intelligence Pro* | Subscription | €149/mo | Monthly recurring |
+
+**Padel Business Plan (€99 one-time):**
+Bank-ready PDF auto-generated from planner inputs. Covers what banks and investors need to see for facility financing (including KfW Gründerkredit in Germany). Available in English and German. Contains:
+
+- **Executive summary** — facility concept, location, key financials at a glance
+- **Market analysis** — padel-specific templated narrative covering target market, competitive landscape, demand drivers. User fills in location-specific details.
+- **Investment plan** — full CAPEX breakdown from planner (courts, construction, equipment, working capital, contingency). Mapped to standard bank categories. Includes budget vs. projected CAPEX comparison.
+- **Revenue & profitability forecast** — 3-year P&L from planner projections. Revenue streams, operating costs by category, EBITDA, net income, available income after debt service and taxes.
+- **Liquidity plan** — 12-month cash flow from planner's monthly model. Inflows, outflows by category, monthly and cumulative balance, financing structure (equity + debt).
+- **Sensitivity analysis** — utilization and pricing sensitivity tables from planner
+- **Key metrics** — IRR, MOIC, DSCR, cash-on-cash, break-even utilization, payback period
+
+Uses the calculator's own numbers and formatting. Clean, professional layout. Not locked to any specific bank's form — but covers everything banks, KfW, and investors ask for.
+
+**Business Plan Pro (€39/mo):**
+Everything above, plus:
+- Unlimited scenario exports (compare indoor vs outdoor, 4-court vs 8-court, etc.)
+- Market data in projections (from Playtomic scraping, when available)
+- Sensitivity analysis appendix with additional scenarios
+- Branded cover page with company logo
+
+### Supplier Products
+
+| Product | Type | Price | Paddle Config |
+|---------|------|-------|---------------|
+| **Supplier Growth** | Subscription | €149/mo | Monthly recurring |
+| **Supplier Pro** | Subscription | €399/mo | Monthly recurring |
+| **Credit Pack 25** | One-time | €99 | One-time charge |
+| **Credit Pack 50** | One-time | €179 | One-time charge |
+| **Credit Pack 100** | One-time | €329 | One-time charge |
+| **Credit Pack 250** | One-time | €749 | One-time charge |
+| **Boost: Logo** | Add-on | €29/mo | Monthly recurring add-on |
+| **Boost: Highlight** | Add-on | €39/mo | Monthly recurring add-on |
+| **Boost: Verified Badge** | Add-on | €49/mo | Monthly recurring add-on |
+| **Boost: Lead Feed Access** | Add-on | €199/mo | Monthly recurring add-on |
+| **Boost: Newsletter Feature** | Add-on | €99/mo | Monthly recurring add-on |
+| **Boost: Sticky Top (1 week)** | One-time | €79 | One-time charge |
+| **Boost: Sticky Top (1 month)** | One-time | €199 | One-time charge |
+
+**Supplier Growth (€149/mo):** Directory listing + 30 credits/mo + basic analytics.
+**Supplier Pro (€399/mo):** Directory listing + 100 credits/mo + full analytics + priority placement.
+
+No free tier for suppliers. Leads are paywalled from day one.
+
+### App-Side Implementation
+
+Products managed through:
+1. **Paddle product catalog** — all products/prices defined in Paddle dashboard
+2. **`products` table in app DB** — maps Paddle product IDs to internal feature flags
+3. **`subscriptions` table** — tracks active subs per user (synced via Paddle webhooks)
+4. **`credits` table** — tracks credit balance per supplier (incremented on purchase, decremented on lead unlock)
+5. **`entitlements` helper** — checks what a user can do: `can_export_pdf(user)`, `can_view_leads(user)`, `has_credits(user, n)`
+6. **Paddle webhook handler** — processes subscription.created/updated/cancelled, transaction.completed for one-time purchases
+
+---
+
+## New Calculator Variables
+
+### Budget Target (`budget`)
+Top-level input in the Assumptions tab. User enters their total budget (e.g. €300K).
+
+**Enables:**
+- **Budget vs. Plan indicator** across Investment tab and Key Metrics: "Your plan costs €340K — €40K over budget"
+- **Savings guidance:** "Switch from panoramic to standard glass to save €24K"
+- **Pre-fills budget** in the quote request brief (validated against a real model, not a guess)
+- **Business plan PDF** shows "Budget vs. Projected CAPEX" — banks value this
+
+### Court Glass Type (`glassType`)
+Pill select in Assumptions tab.
+
+Options: `panoramic` (full panoramic glass walls, higher cost) / `standard` (standard glass walls) / `no_preference`
+
+Affects: court cost per unit in CAPEX calculation. Pre-fills into quote request brief.
+
+### Lighting Type (`lightingType`)
+Pill select in Assumptions tab.
+
+Options: `led_competition` (competition-grade, higher cost) / `led_standard` (standard, moderate cost) / `natural` (natural light / outdoor, no lighting CAPEX)
+
+Affects: lighting line item in CAPEX calculation. Pre-fills into quote request brief.
+
+---
+
+## "Get Builder Quotes" — Lead Qualification Flow
+
+3-step form designed for maximum lead qualification. Pre-fills from calculator state where possible. Reference: `padelnomics-demand-side.jsx`.
+
+### Step 1: Project Specs
+
+Pre-filled from calculator, editable by user.
+
+| Field | Source | Options |
+|-------|--------|---------|
+| Facility type | Calculator (venue type) | Indoor / Outdoor / Both indoor & outdoor |
+| Number of courts | Calculator (dblCourts + sglCourts) | 1–16 slider |
+| Court glass type | Calculator (glassType) | Panoramic glass / Standard glass / No preference yet |
+| Lighting | Calculator (lightingType) | LED competition / LED standard / Natural light only / Not sure yet |
+| Build context | Brief-only | New standalone facility / Adding to existing sports club / Converting existing building |
+
+### Step 2: Project Details
+
+Lead qualification fields — not in calculator.
+
+| Field | Type | Options |
+|-------|------|---------|
+| City / Region | Text input | e.g. "Göttingen, Lower Saxony" |
+| Country | Dropdown | Germany, Netherlands, France, Italy, Spain, UK, Sweden, Belgium, Austria, Switzerland, Portugal, UAE, USA, Other |
+| Timeline | Pill select | ASAP (< 3 months) / 3–6 months / 6–12 months / 12+ months (exploring) |
+| Budget | Pre-filled from calculator | Editable. Shows "Based on your plan: €340K" if coming from planner |
+| Location status | Pill select | Lease/purchase signed / Shortlisted locations / Still searching |
+| Financing status | Pill select | Self-funded / Bank loan approved / Seeking financing / Not started |
+| *(If "Seeking financing")* | Conditional | "Would you like help finding padel facility financing?" — Yes, connect me with financing partners / No, just builder quotes for now |
+| Decision process | Pill select | Solo decision / Business partners / Club board or committee |
+| Previous supplier contact | Pill select | Already received quotes / Talked to some / This is my first step |
+| Services needed | Multi-select pills | Court construction (turnkey), Court surfaces only, Steel structures / canopy, Glass walls, Lighting systems, Flooring / foundation, Architecture & planning, Consulting / feasibility |
+| Additional info | Textarea | "E.g. converting an existing warehouse, need planning permission support..." |
+
+### Step 3: Contact Details
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| Name | Yes | |
+| Email | Yes | Also creates account if not logged in |
+| Phone | Optional | |
+| Company / Organization | Optional | |
+
+Shows summary card of all selections before submission.
+Privacy notice: "Your contact details are shared only with matched, paying suppliers. No spam, no public listing."
+
+### After Submission
+
+- Lead stored in `lead_requests` with all fields + linked to scenario if user was logged in
+- Confirmation page with "What happens next" steps
+- Confirmation email sent to user
+- Lead appears in supplier lead feed (anonymized until unlocked with credits)
+- Heat score auto-calculated from readiness signals:
+
+| Signal Combo | Heat | Credit Cost |
+|---|---|---|
+| Location secured + financing approved/self-funded + timeline <6mo + solo decision | Hot | 30–40 credits |
+| Shortlisted + seeking financing + 6–12mo + partners | Warm | 15–25 credits |
+| Still searching + not started + 12+mo + committee | Cool | 5–10 credits |
+
+- If "Yes, connect me with financing partners" → flagged as financing lead for future Phase 2–3 monetization
+
+---
+
+## Builder Directory
+
+Public directory at `/directory` showing court builders and suppliers.
+
+### Listing Structure
+
+Each listing shows:
+- Company name + logo (if Logo boost active)
+- Service area (countries/regions)
+- Specialties (turnkey, surfaces, glass, lighting, structures, etc.)
+- Short description
+- Project count / years in business
+- Verified badge (if Verified boost active)
+- "Request Quote" CTA → links to the lead qualification flow
+
+### Directory Layout
+
+- Grid/list view of suppliers
+- Filter by: country, service type, specialty
+- Sort by: relevance (default, weighted by boost level), newest
+- Highlighted listings (if Highlight boost active) get colored border/background
+- Sticky top placements (if Sticky boost purchased) pinned above organic results
+
+### Boost Effects
+
+| Boost | Effect in Directory | Effect on Profile |
+|-------|--------------------|--------------------|
+| Logo (+€29/mo) | Company logo shown next to name | Logo on profile page |
+| Highlight (+€39/mo) | Colored border, stands out in list | Featured badge |
+| Verified (+€49/mo) | "Verified" badge | Trust signal |
+| Lead Feed (+€199/mo) | — | Access to anonymized project briefs |
+| Newsletter (+€99/mo) | — | Featured in monthly newsletter to entrepreneurs |
+| Sticky 1wk (€79) | Pinned to top of results for 1 week | — |
+| Sticky 1mo (€199) | Pinned to top of results for 1 month | — |
+
+### Supplier Signup Flow
+
+Reference: `padelnomics-supplier-signup.jsx`. Built in Quart/HTMX.
+
+1. **Choose plan** — Growth (€149/mo) or Pro (€399/mo). Show what's included.
+2. **Add boosts** — pre-selected "recommended" bundle (Logo + Highlight + Verified = +€117/mo). Show visibility multiplier ("3.2x more visibility vs basic listing"). Loss aversion: all recommended boosts pre-checked, user opts out.
+3. **Extra credits** — optional credit packs if they want more leads beyond monthly allocation
+4. **Account details** — company name, contact, email, country, service categories
+5. **Paddle checkout** — processes subscription + any add-ons/one-time purchases
+
+---
+
+## Phase 0 — Ungate & Validate (Weeks 1–2)
+
+**Goal:** Get distribution flowing. Validate that builders will pay for leads.
+
+### 0.1 Guest Mode Planner
+- Remove `@login_required` from `/planner/` and `/planner/calculate`
+- Planner works fully without signup — all 6 tabs, all inputs, all outputs
+- Disable scenario save/load/compare for guests (show "Sign up to save" prompt)
+- Ensure planner page is SEO-indexable (meta tags, og:image, structured data)
+
+### 0.2 New Calculator Variables
+- Add budget target input to Assumptions tab with over/under indicator on Investment tab and Key Metrics
+- Add court glass type (panoramic/standard/no preference) to Assumptions tab
+- Add lighting type (LED competition/standard/natural) to Assumptions tab
+- Wire into CAPEX calculation
+
+### 0.3 CTAs on Planner Results
+Two CTAs visible after the user has results:
+
+**"Export Business Plan (PDF)" → €99**
+- Requires signup → Paddle checkout
+- Auto-generates bank-ready PDF from current planner state (EN or DE)
+
+**"Get Builder Quotes" → 3-step lead qualification flow**
+- Pre-fills from calculator state (court count, type, glass, lighting, budget)
+- Captures readiness signals (location status, financing, decision process, previous contact)
+- Stores in `lead_requests` with heat score
+- Confirmation page + email
+
+### 0.4 Builder Outreach & Paid Validation
+- Reach out to 5–10 German court builders
+- Pitch: "We have entrepreneurs planning padel facilities. Pay per lead to connect."
+- Offer Growth plan (€149/mo) or credit packs
+- Goal: 1+ paying builder within 2 weeks
+- No free tier, no free trial — validate willingness to pay immediately
+
+### 0.5 SEO Validation
+- Research keyword volumes: "padel halle kosten," "padel court cost," "padel business plan," "padel hall bauen"
+- Target: confirm >500 combined monthly searches
+
+### 0.6 First SEO Article
+- "How Much Does It Cost to Open a Padel Hall in 2026?"
+- Link to the planner
+- Publish on padelnomics.io/blog
+
+**Exit criteria:**
+- [ ] Planner accessible without login
+- [ ] New calculator variables (budget, glass type, lighting) live
+- [ ] Business plan PDF export working (Paddle checkout → PDF generation)
+- [ ] "Get Builder Quotes" 3-step flow live and capturing qualified leads
+- [ ] 1+ builder paying for lead access
+- [ ] Keyword volumes confirmed
+
+---
+
+## Phase 1 — Revenue Engine (Weeks 3–8)
+
+**Goal:** Both revenue streams producing. Builder directory live. Content flywheel started. Data moat seeded.
+
+### 1a. Lead Operations (Weeks 3–4)
+- Admin view to manage incoming quote requests
+- Lead forwarding to paying builders (automated email with project brief)
+- Email nurture sequence for planner users who didn't convert
+- Track conversion: planner completions → quote requests → builder unlocks → deals
+
+### 1b. Builder Directory (Weeks 3–5)
+- Public directory at /directory
+- All listings require paid subscription (Growth €149/mo or Pro €399/mo)
+- Company profiles: name, logo, service area, specialties, description, projects
+- Boost upsells: logo, highlight, verified badge, sticky placements
+- Pre-selected "recommended" bundle during signup
+- Visibility multiplier display
+- "Request Quote" CTA on each listing → leads to quote flow
+- Built in Quart/HTMX, using supplier-signup.jsx as design reference
+
+### 1c. Content & SEO (Weeks 3–6)
+- 2 more SEO articles:
+  - Passive stage: "Is Padel Still a Good Investment in 2026? The Data Says..."
+  - Deciding stage: "What Banks Want to See in a Padel Business Plan"
+- Programmatic city pages from Playtomic data (/markets/berlin, /markets/munich, etc.)
+- Post to padel communities (Reddit, Facebook groups, padel forums)
+
+### 1d. Data Pipeline — padelnomics-data (Weeks 3–6, parallel track)
+Separate `padelnomics-data` package in the uv monorepo. ELT-style architecture.
+
+- **Extract:** Scraper API for Playtomic data (venues, availability, pricing)
+- **Load/Transform:** sqlmesh + DuckDB
+- **Output:** Market-informed defaults flowing back into the planner (avg pricing by region, typical court counts)
+- Basic public market map (builds authority + SEO)
+- Historical storage from day 1 (the moat compounds daily)
+
+*Data engineering architecture to be discussed separately.*
+
+### Revenue target: €1K–2K/mo
+- Builder subscriptions: 2–3 × €149–399/mo
+- Credit purchases from builders
+- Business plan PDF exports: 5–10 × €99
+
+---
+
+## Phase 2 — Scale the Marketplace (Months 3–6)
+
+**Goal:** Automated lead marketplace. Supplier dashboard live. €3K–5K MRR.
+
+### 2a. Supplier Landing Page (/suppliers)
+- Dedicated landing page selling to builders
+- Value prop: "Get connected with entrepreneurs planning padel facilities"
+- Show: monthly lead volume, average project value, how credits work
+- Social proof: "X projects planned this month, €Y total investment value"
+- Pricing table with Growth/Pro plans + boost add-ons
+- CTA: "Start Getting Leads" → signup flow
+
+### 2b. Supplier Dashboard
+- Dashboard tab: KPIs (profile views, leads unlocked, credits balance, directory rank)
+- Lead feed tab: browse + filter anonymized project briefs, unlock with credits
+- My listing tab: preview how company appears, performance metrics (views, clicks, contact requests)
+- Boosts tab: toggle add-ons, see visibility multiplier, update plan
+- Built in Quart/HTMX, using supplier-dashboard.jsx as design reference
+
+### 2c. Lead Feed & Credits
+- Anonymized project briefs visible to subscribed builders
+- Heat scoring from readiness signals (location status, financing, timeline, decision process)
+- Credit cost scales with heat + project size
+- Bidder count visible ("2 suppliers already unlocked — be first in your region!")
+
+### 2d. Business Plan Pro (€39/mo subscription)
+- Upgrade from one-time PDF
+- Unlimited scenario exports
+- Market data integration (when available from padelnomics-data)
+- Sensitivity analysis appendix
+- Branded cover page
+
+### 2e. Market Map (Public)
+- Interactive map of padel venues (from padelnomics-data pipeline)
+- Court density, pricing ranges, basic occupancy indicators
+- City-level aggregate stats
+- Drives SEO, demonstrates data capability
+- Teaser for future paid intelligence product
+
+### 2f. Financing Leads (if validated)
+- If enough "Yes, connect me with financing partners" signals accumulated in Phase 0–1
+- Approach banks/lenders: "We have X entrepreneurs/mo seeking facility financing"
+- Same credit-based marketplace model, different supply side
+
+### Revenue target: €3K–5K MRR
+- 5–8 builder subscriptions × €149–399/mo
+- Credit revenue from lead unlocks
+- Business plan exports (one-time + subscription)
+- Boost add-on revenue
+
+---
+
+## Phase 3 — Data & Intelligence (Months 6–12)
+
+**Goal:** Data moat becomes a product. €5K–10K MRR. Monetize the entrepreneur side with intelligence.
+
+*Exact shape depends on what we learn in Phases 0–2. This is directional.*
+
+### 3a. Market Intelligence Dashboard (Paid)
+By now we have 6+ months of historical data + hundreds of completed plans.
+
+- Explorer tier (€79/mo): city-level stats, monthly trends, market map with overlays
+- Pro tier (€149/mo): venue-level data, competitor tracking, site selection scoring, historical data, export
+- Features: occupancy heatmaps, pricing benchmarks, demand gap analysis, competitor alerts, growth trends
+
+### 3b. Operator Analytics
+- For venue owners already running halls
+- Benchmark performance vs. market (occupancy, pricing, revenue/court)
+- Pricing optimization from scraped competitor data
+- Competitor monitoring alerts (new venues, pricing changes)
+- Natural upsell for planner users who actually built their facility
+
+### 3c. Premium Products
+- Site Selection Reports (€499–999): custom location analysis
+- Quarterly "State of Padel" reports: builds authority, generates enterprise leads
+- Financing partner integrations (full lending marketplace)
+
+### Revenue target: €5K–10K MRR
+
+---
+
+## Phase 4 — Scale (Months 12–18+)
+
+**Goal:** Pan-European. €10K+ MRR.
+
+- Geographic expansion: DACH → Western Europe → global
+- Additional language support
+- Multi-source data aggregation (beyond Playtomic)
+- Enterprise tier for franchises, RE developers, investors
+- API / data licensing
+- Newsletter monetization ("The Padel Business Report")
+- Productized consulting (Padel Hall Accelerator, €999)
+- ML/forecasting layer on accumulated data
+
+---
+
+## Revenue Model Summary
+
+| Phase | Timeline | Source | Target MRR |
+|-------|----------|--------|------------|
+| 0 | Weeks 1–2 | Business plan PDF + first builder payments | €0–500 |
+| 1 | Weeks 3–8 | Builder subs + credits + PDF exports + directory | €1K–2K |
+| 2 | Months 3–6 | Scaled marketplace + Business Plan Pro sub | €3K–5K |
+| 3 | Months 6–12 | + Market intelligence subs + premium reports | €5K–10K |
+| 4 | Months 12–18 | + Enterprise + API + consulting | €10K+ |
+
+---
+
+## Key Assumptions to Validate
+
+| # | Assumption | How to Test | Success Signal | Phase |
+|---|-----------|-------------|----------------|-------|
+| 1 | Builders will pay for leads | Direct outreach, no free trial | 1+ builder paying in week 2 | 0 |
+| 2 | SEO can drive traffic | Keyword volume research | >500 combined monthly searches | 0 |
+| 3 | Open planner → quote requests | Track completions → CTA clicks | >5% conversion to quote request | 0–1 |
+| 4 | Entrepreneurs will pay €99 for bank-ready PDF | Build it, sell it | 5+ sales in first month | 1 |
+| 5 | Playtomic data is scrapable at scale | Build pipeline, run 2 weeks | Stable daily scrape | 1 |
+| 6 | Builders prefer subscription over per-lead | Offer both | 30%+ choose subscription | 2 |
+| 7 | Financing lead demand exists | Count "connect me with financing" signals | 20%+ of leads request financing help | 0–1 |
+
+---
+
+## Tech Stack
+
+### padelnomics (web app)
+- **Backend:** Quart (async Python) + aiosqlite
+- **Frontend:** Vanilla JS + HTMX + Tailwind CSS v4 + Chart.js
+- **Auth:** Magic links (existing)
+- **Payments:** Paddle (products, subscriptions, one-time charges, webhooks)
+- **PDF generation:** TBD (WeasyPrint or similar Python PDF library)
+- **Deployment:** Docker + GitLab CI/CD + blue-green deploys (existing)
+
+### padelnomics-data (data pipeline)
+- Separate package in the uv monorepo
+- **Extraction:** Scraper API
+- **Transformation:** sqlmesh + DuckDB
+- **Architecture:** ELT-style, batch extraction
+- *Details to be discussed separately.*
+
+React prototypes used as **design reference only** — everything built in Quart/HTMX:
+- `padelnomics-demand-side.jsx` → quote request flow
+- `padelnomics-supplier-signup.jsx` → supplier signup
+- `supplier-dashboard.jsx` → supplier dashboard
+
+---
+
+## What We're NOT Doing (Yet)
+
+Parked until Phase 3+ or until demand proves it:
+- Operator dashboards / ERP features
+- AI scenario advisor
+- Franchise toolkit
+- M&A intelligence
+- Mobile app
+- Paid advertising
+- Free tiers for suppliers
+- Full financing marketplace (capturing intent signal only for now)