Data Flow

Customer Journey:
  Website Form → N8N Webhook (popn-contact)
       OR
  Phone Call → Vonage → AI Voice Agent (Cartesia)
       ↓
┌─────────────────────────────────────┐
│         N8N Workflow Engine         │
├─────────────────────────────────────┤
│ POPN-webform (contact form)        │
│ POPN-create-booking                │
│ POPN-get-slots                     │
│ POPN-cancel-booking                │
│ POPN-payment-link (Stripe)         │
│ POPN-stripe-event (payment conf.)  │
│ POPN-voice-events                  │
│ POPN-config (config server)        │
└─────────────────────────────────────┘
       ↓                    ↓
  Google Calendar      Config Server
  (per performer)    (.POPN-variables.json)
       ↓
  Admin Portal (this app)
  - Pricing management
  - Performer management
  - SMS templates
  - Integration config

Tech Stack

Executive Summary

Poppin' Parties TX is a vertically-integrated, automation-first kids' entertainment platform currently operating across 6 Texas metros (127 cities, 642 SEO landing pages). The thesis: a tiny operating-cost footprint (~$56/mo at typical volume) combined with high-leverage automation (booking, payments, AI phone, dispatch) creates an asymmetric scaling opportunity. Each new geographic territory or vertical adds revenue at ~3% marginal cost overhead, with the rest going to performer payout, marketing, and contribution margin. This plan outlines a 5-phase scaling roadmap from local Texas operator → multi-state platform → licensed network.

Strategic Framework — Ansoff Growth Matrix

The Ansoff Matrix is a classic 2×2 strategy tool that maps four ways a business can grow: sell more of what you have to existing customers, sell new things to existing customers, take what you have to new markets, or do something completely new. We tackle them in order of risk.

Four orthogonal growth vectors. Phases 1–5 sequence them by capital intensity and operational risk.

5-Phase Scaling Roadmap

Op Margin (operating margin) = the % of revenue left after running the business but before taxes & interest. ROAS = return on ad spend (revenue per $1 of ads). AOV = average order value per booking.

*Operating margin after performer payout (~50% of revenue), processing fees (3%), system cost (~0.3%), and marketing spend (CAC scales from ~12% Phase 1 → ~7% Phase 4 due to brand + SEO compound effect).

Revenue Trajectory

Annual revenue progression across phases (log-friendly visual; bar widths proportional to revenue).

TAM / SAM / SOM Analysis

TAM (Total Addressable Market) = the entire pie if every dollar of demand were ours. SAM (Serviceable Addressable Market) = the slice we could realistically reach with our service mix and geography. SOM (Serviceable Obtainable Market) = the realistic slice of that we expect to capture given competition and capacity.

Sizing the U.S. children's-entertainment + corporate event entertainment opportunity. IBISWorld-style breakdown.

Vertical Expansion (Product Development)

A “vertical” is a customer category with its own buying patterns (e.g., kids' parties vs. corporate events vs. schools). AOV = average order value. B2C = direct-to-consumer; B2B = business-to-business. LTV = lifetime value of a customer (recurring revenue over time). MRR = monthly recurring revenue (the SaaS-style retainer line).

Same artist crew, different packaging. Each vertical lifts blended AOV and adds recurring revenue.

Geographic Expansion (Market Development)

An SEO factory is our system for auto-generating hundreds of city-specific landing pages so every Google search like “face painter in [city]” finds us. A tenant is an isolated copy of the booking system for a region.

Each tier replicates the proven TX playbook: SEO factory (≈100 city pages) + 8–12 contractor artists + N8N tenant + ad account. Time-to-launch per market: 30–60 days.

Unit Economics — Per-Booking Contribution

Unit economics = the profit math on a single transaction (one booking). CAC (Customer Acquisition Cost) = average ad & marketing spend to win one booking. Contribution margin = what's left after the variable costs of that booking; it's what funds fixed overhead and profit. Operating leverage = the fact that fixed costs spread over more bookings, so each new booking is more profitable than the last.

Standard $300 booking, kids' party (B2C). Margin improves with B2B / packages. Numbers in $.

Operating leverage: system cost per booking falls from $0.56 → $0.20 (−64%) as fixed infra is amortized over more volume. CAC drops as organic SEO compounds and brand recall lifts repeat-customer share (~25% by Phase 3). Performer payout stays fixed at 50% — the contribution-margin lift comes from everything else getting cheaper per booking.

Margin Curve at Scale

EBITDA = Earnings Before Interest, Taxes, Depreciation & Amortization — a standard way to compare operating profitability across companies of different sizes. Higher EBITDA % means more of every revenue dollar drops to the bottom line.

EBITDA margin progression as fixed costs spread and software/license revenue mixes in.

Revenue Mix Evolution

% of total revenue by line. Diversification reduces single-channel risk.

Capital Requirements by Phase

FTE = Full-Time Equivalent (one full-time employee, or a combination of part-timers totaling one). Payback = how long until the investment earns itself back in profit.

Key Risks & Mitigations

SOP = Standard Operating Procedure (a written, repeatable how-to guide). GL policy = General Liability insurance. 1099 contractor = independent contractor (vs. W-2 employee) — they're paid per gig and handle their own taxes.

5-Year Financial Snapshot

EBITDA = operating profit before interest, taxes, depreciation, and amortization. Cumulative Invested = total capital deployed up to that point (compare to EBITDA to see when investment pays back).

Conservative case. Assumes successful Phase transitions on schedule.

Phase 5 (licensed platform) is upside not modeled in the 5-year plan; expected to push Y6+ revenue to $26M+ at 42%+ margin if executed.

The Compounding Advantage

What makes this scalable isn't any single tactic — it's the compounding effect of three layered moats:

1. SEO factory: 642+ landing pages today; +400/state means 2,500+ pages by Phase 3. Organic traffic is a non-linear marketing flywheel — it's near-zero marginal cost and compounds month-over-month.
2. Automation cost-per-booking: $0.56 today, falling to $0.20 by Phase 4. That ~$0.36 per-booking gap is pure margin recapture as we scale, while competitors using manual booking pay $5–$15 per booking in admin labor.
3. Multi-vertical demand stack: kids' parties drive weekend supply utilization; corporate, schools, festivals fill weekday capacity. Performer utilization rises from ~35% (B2C-only) to ~70% by Phase 3 — same headcount, double the revenue.

Most local entertainment businesses plateau at $250K–$500K because every new booking requires a phone call, a calendar lookup, a manual quote, a paper invoice, and chasing payment. We've eliminated all five with automation that costs <$100/mo. Every dollar above the Phase 1 plateau is contribution-margin dollars our competitors structurally can't earn.

Face Painting OR Balloon Twisting

1 artist provides the service. Same pricing for either service.

Bubble Party

Includes bubble machines, wands & pools. Outdoor recommended.

Caricatures OR Glitter Tattoos

1 artist. ⚠️ Caricatures NOT available in Houston region.

Live Glitter Fashion Drawing

1 artist. Premium service — no 1.5hr or 2.5hr options.

Travel Fee

• Flat $25 within 80-mile radius
• Radius measured from HQ (14201 Coyote Trail, Haslet TX) or assigned contractor's base location
• Beyond radius: contact for custom quote

Payment Structure

• Deposit: 30% non-refundable (unless Poppin' cancels → full refund)
• Final Balance: Remaining 70% collected 3 days before event
• Method: Stripe Payment Links sent via SMS

End-to-End Booking Process

Two-Stage Stripe Payment Links

Stage 1: Deposit
  Customer confirms → N8N creates Stripe Payment Link (30%)
  → Vonage sends SMS with link
  → Customer pays
  → Stripe webhook fires checkout.session.completed
  → N8N triggers "Booked" confirmation + calendar event

Stage 2: Final Balance (3 days before event)
  Scheduled N8N trigger
  → Creates Stripe link for remaining 70%
  → Vonage sends SMS with link + artist info
  → Customer pays
  → Stripe webhook confirms → event fully paid

Setup

• Create Stripe account for Poppin' Parties TX
• Add publishable key + secret key in Integrations tab
• Set up webhook endpoint: https://n8n.optimus.systems/webhook/popn-stripe-event
• Subscribe to event: checkout.session.completed

Payment Link API

N8N workflow creates payment links dynamically via POST /v1/payment_links with amount, description, and metadata (booking ID, customer name).

Phone Number

Vonage number: +1 (972) 777-6725

Capabilities

• SMS: Send/receive text messages (payment links, confirmations, reviews)
• Voice: Inbound call routing to AI agent, outbound lead follow-up

Overview

Bella is the Cartesia Line AI voice agent that handles inbound calls on +1 (972) 777-6725. She answers availability questions, quotes prices, creates/cancels bookings, and can transfer callers to team members via sequential ringing.

Capabilities

• Inbound: Answer availability questions, quote prices, take booking details, check calendar
• Booking: Create and cancel bookings via N8N workflows
• Pricing: Real-time quotes for all services and durations (1-8hr events)
• Transfer: Sequential ringing — rings performers in priority order per region

📞 Phone Routing Modes

Control how inbound calls are handled from the Phone Routing tab:

🔔 Sequential Ringing

When a call is transferred, the system rings team members one at a time:

1. On Call performer rings first (if set) — covers ALL regions
2. Regional priority performers ring in order (lower number = rings first)
3. Performers outside working hours are skipped (if "Respect working hours" is enabled)
4. Each performer rings for the configured Max Ring Time before trying the next
5. If nobody answers, the customizable No-Answer Message is spoken to the caller

How to Configure

1. Go to Phone Routing tab
2. Select a routing mode
3. Optionally set an On Call performer (rings first for all regions)
4. In the Regional Routing Priorities table, set priority numbers per region (1 = rings first, blank = skip)
5. Use arrow keys or type a number. Set to 0 or delete to clear a priority.
6. Click Save Changes

🔧 Technical Details

• Platform: Cartesia Line SDK v0.2.8 + Groq GPT-OSS (LLM)
• Voice: Jacqueline (Cartesia Sonic 3 TTS + Ink STT)
• Agent ID: agent_fSTWNXEz2wi7fqNoTEiBAB
• Phone: +1 (972) 777-6725 (Vonage Voice API)
• Transfer: Vonage NCCO sequential connect via HMAC-signed answer URL
• Deploy: cd cartesia-agent && ./deploy.sh

Overview

775 auto-generated SEO pages across 6 regions. Generated by node generate-seo-pages.js. Do not hand-edit — they are overwritten by the generator.

• 642 city + service pages (e.g., /face-painting-dallas-tx)
• 127 per-city all-services hubs (e.g., /party-entertainment-dallas-tx) — sitemap priority 0.85
• 6 regional hero pages (e.g., /dfw-tx) — sitemap priority 0.9

🔥 Regional Hero Pages

High-priority landing pages, one per metro region. Each includes a services grid + full city directory.

Core Service Pages

Payment Status Colors

Calendar events automatically change color as payments are received:

How It Works

• New bookings are created with tangerine (unpaid)
• When Stripe fires checkout.session.completed, the POPN - Payment Received N8N workflow updates the event color and description
• Payment status is only visible to owners in the calendar description (artists see event details only)
• You can also manually record a payment via the webhook (see BOOKING-AUTOMATION-SYSTEM.md)

Core Integrations

Infrastructure

Getting Started

• Sign in with an authorized Google account (set in Admin Users tab)
• All changes auto-save after a 1.5s delay or when clicking Save
• The ⚡ indicator shows unsaved changes

Tabs Reference

Overview

The Messages tab is a two-way SMS inbox showing every text sent to or from +1 (972) 777-6725 — including booking confirmations, payment links, Bella's auto-replies, and customer responses. Admins can manually reply to any active conversation in real time.

📥 What Gets Logged

• Inbound — every SMS from a customer (received via Vonage webhook)
• Outbound — booking confirmations, payment link SMS, reminders (logged by N8N workflows)
• Bella replies — texts sent by the AI voice agent (tagged with 🤖 Bella)
• Admin replies — manual sends from this portal (tagged with admin email)
• Auto-replies — STOP/START/HELP keyword confirmations sent automatically

🚫 SMS Opt-Out Compliance (CTIA / 10DLC)

US carriers require all SMS senders — even transactional — to honor opt-out keywords. Failing to do so risks number suspension and 10DLC campaign revocation.

Disclosure Footer

The first SMS in any new conversation should include: "Reply STOP to opt out, HELP for help. Msg & data rates may apply." This is a CTIA best practice for all commercial SMS.

Using the Messages Tab

1. Conversations are listed in the left panel, sorted by most recent activity
2. Filters: All · Unread · Active · Opted Out
3. Search by customer name, phone, message text, or booking reference
4. Click a conversation to view the full thread
5. Type a reply at the bottom (Cmd/Ctrl+Enter to send)
6. Opted-out conversations are greyed out and the reply box is disabled — server enforces this regardless of UI state
7. Manual opt-out: click "🚫 Opt Out" in the thread header (e.g. customer requested verbally)
8. Re-enable: click "↻ Re-enable SMS" — only do this with documented customer consent (logged for compliance)

Email Compliance (CAN-SPAM)

Currently all email traffic is internal (notifications to admins/dispatch), so CAN-SPAM does not apply. If customer-facing email is ever added (booking confirmations to customers, marketing newsletters), the system will need:

• Unsubscribe link in every commercial email (10-day honor window)
• Valid physical postal address in footer
• Truthful "From" / subject lines
• The contact_opt_outs table is already designed with a channel column to support email opt-outs without a migration

FastAPI Backend Endpoints