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

Website	Static HTML/CSS/JS, 280 SEO pages
Admin Portal	Vanilla HTML/CSS/JS SPA
Config Server	Express.js on port 3002
Workflows	N8N (self-hosted at n8n.optimus.systems)
Payments	Stripe Payment Links API
SMS	Vonage Messages API
Voice AI	Cartesia Line Agent + GROQ LLM
Calendar	Google Calendar API (OAuth2)

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

#	Step	Trigger	Action
1	Inquiry	Website form or phone call	N8N receives submission, emails owner + confirms customer
2	Quote	KateLyn reviews	Send SMS with price breakdown (base + travel) + service menus
3	Accept	Customer says yes	Send 30% deposit Stripe link via SMS
4	Booked	Stripe webhook: deposit paid	Confirm booking, create calendar event, assign performer
5	Reminder	3 days before event	Send final balance Stripe link + artist info via SMS
6	Event Day	Final payment confirmed	Send event confirmation + artist contact
7	Follow-up	1 day after event	Send Google review request via SMS

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

Cartesia Line AI agent handles inbound and outbound calls with a fun, party-themed personality matching the Poppin' Parties brand.

Capabilities

• Inbound: Answer availability questions, quote prices, take booking details, check calendar
• Outbound: Follow up on website form submissions that haven't converted
• Pricing: Query config server for real-time quotes (up to 8hr events)
• Handoff: Transfer to KateLyn for complex requests

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

🏢 Business	Company info, address, travel fee, deposit %, payment timing
🎨 Performers	Add/edit performers — name, skills, calendar, working hours, base location
💰 Pricing	Edit all service prices (1-8hr) for individual & packages
📅 Scheduling	Booking rules (advance time, max duration, slot intervals) + regions
💬 SMS Templates	Customize automated messages — use {{variables}} for dynamic content
🔗 Integrations	Vonage, Stripe, N8N webhook URLs
👤 Admin Users	Manage authorized Google accounts + Google OAuth client ID
📚 Docs	This documentation section

Config Server API

Endpoint	Method	Auth	Description
/health	GET	None	Health check
/config	GET	Optional	Full config (secrets masked without API key)
/config	POST	X-API-KEY	Update config sections
/pricing/quote	GET	None	Calculate price quote

Quote API Example

GET /pricing/quote?services=face-painting,balloon-twisting&duration=2&city=Dallas

Response:
{
  "services": "Face Painting + Balloon Twisting",
  "duration": 2, "basePrice": 350,
  "travelFee": 25, "totalPrice": 375,
  "depositPercent": 30, "depositAmount": 113,
  "balanceAmount": 262, "artistsRequired": 2
}