Enabled	Tool name	N8N webhook	Description
	`check_service_area`	`/webhook/popn-dispatch` (coverage-only)	Verify city is in service area + return region slug
	`get_pricing_quote`	`/api/popn/pricing/quote/` (DB)	Compute service + travel + add-ons (DB-driven)
	`get_available_slots`	`/webhook/popn-dispatch`	Score artists for a specific date/time/city
	`check_artist_availability`	`/api/popn/availability/` (DB, real-time)	Pre-transfer: is anyone free RIGHT NOW? Returns reason code
	`create_booking`	`/webhook/popn-create-booking`	Persist booking + dispatch Square payment link via SMS
	`cancel_booking`	`/webhook/popn-cancel-booking`	Mark booking cancelled, notify performer + customer
	`notify_region_owner`	`/webhook/popn-owner-notifications`	Escalate rush/complaint/custom request to regional manager (SMS+email)
	`forward_message`	`/webhook/popn-internal-notifications`	Take a message for a specific staff member when transfer isn't possible
	`initiate_transfer`	(NCCO connect → sequential ring)	Live transfer to artist via Vonage. Requires `check_artist_availability` first
always	`end_call`	(bridge-internal hangup)	Required at end of every non-transferred call. Bella must emit alongside her farewell

📚 Poppin' Partiez — System Docs

v1.0.0

About This System

The Poppin' Partiez automation platform handles booking inquiries, guided Scheduling review, automated quoting, Square hosted payment links, invoice/receipt PDFs, SMS/email notifications, optional Team Microsoft/Google calendar sync, and AI-powered phone support across DFW, Houston, Austin, San Antonio, Waco/Temple, and Stephenville/De Leon metro areas.

Website: PoppinPartiez.com — 775 SEO pages (642 city+service + 127 city hubs + 6 regional hubs)
Contact Form: Webhook → N8N → durable form row → unassigned Scheduling request
Finalization: Admin or AI confirms artist, base price, travel fee, and payment type before workflows run
Manual Actions: Human-triggered payment requests, invoices, receipts, corp files, and schedule overrides are logged with context and audit notes
AI Placeholders: Bella and future AI operators prepare recommendations through the same review package; backend validation decides what can finalize
Payment: Square hosted links or invoice/receipt workflows with PDFs and payment history
Scheduling: FastAPI booking records, with optional Team Microsoft/Google calendar sync
Phone: Vonage + OpenAI GPT Realtime AI voice agent for inbound/outbound
Admin: This portal (admin.poppinpartiez.com)

📊 Books & Finance Operations

The Books documentation now lives near the top of the left sidebar under 📊 Books → Finance Operations. It summarizes the read-only Dev Books tab, future double-entry ledger, bank feeds, owner distributions, K-1/TurboTax owner worksheets, IRS reporting, Texas reporting, exports, and rollout phases.

💵 Systems Expenses Breakdown

Monthly cost estimate for the underlying infrastructure and third-party services that power the booking automation, AI phone agent, SMS, calendar, and website. System costs are everything you wouldn't pay for if you ran the business manually. Payment processing fees are listed separately below — those are a cost of doing business and would apply with or without this platform (any time you accept a card). Usage-based services are estimated at low / typical / high volume tiers (30 / 100 / 250 bookings per month). Vendor list prices as of May 2026.

Fixed Monthly Costs

Service	What it does	Plan	Cost / mo
VPS Hosting (212.38.95.250)	Single Linux server running nginx, N8N, PostgreSQL, FastAPI backend, Traefik (SSL), and the Optimus Ops platform — all in Docker	Hetzner-class CX22 / CPX21 (4 vCPU, 8 GB RAM, 80 GB SSD)	~$8 – $15
Domain Names	`poppinpartiez.com` + legacy `poppinpartiestx.com` / `poppinpartieztx.com` compatibility domains	Registrar (annual ÷ 12)	~$2 – $4
Vonage Phone Number	Toll-free presence: +1 (972) 777-6725 for SMS + voice	1 long-code US number	~$1.00
Vonage 10DLC Registration	US carrier-required registration for business SMS (one brand + one campaign). For private/local brands, leave stock symbol and stock exchange blank/none.	Brand $4 + Standard campaign $10/mo	~$10 – $15
Google (free Gmail)	Free Gmail account (poppinpartiesinqury@gmail.com) — Gmail OAuth for N8N + shared Google Calendar per performer	Free tier	$0
OpenAI GPT Realtime (voice agent)	Hosts "Bella" — single integrated speech-to-speech model (`gpt-realtime`) through the FastAPI bridge. Replaces the legacy Cartesia STT + Sonic TTS + Groq LLM stack.	Pay-as-you-go — usage billed below	$0 base
Cartesia / Groq (legacy)	Off. Cartesia agent archived; Groq LLM no longer in the call path. Kept for historical reference.	—	$0
GitHub	Source repos for website, backend, voice bridge, N8N workflows	Free tier (private repos)	$0
Fixed monthly subtotal			~$21 – $35 / mo

Usage-Based Costs (per booking funnel)

Service	Unit price	Per booking	30 / 100 / 250 bookings
Vonage SMS (outbound)	~$0.0083 / segment + ~$0.005 carrier fee = ~$0.013 / msg	~6–8 messages (quote, deposit link, reminders, balance link, artist intro, review request) ≈ $0.10	$3 / $10 / $25
Vonage SMS (inbound)	~$0.0075 / msg	~3–5 customer replies ≈ $0.04	$1 / $4 / $10
Vonage Voice (inbound to AI)	~$0.0085 / min inbound	~3–5 min avg call ≈ $0.04	$1 / $4 / $11
OpenAI GPT Realtime Voice	Direct OpenAI token billing: `gpt-realtime` audio in $32/M tokens, audio out $64/M tokens. Planning estimate: ~$0.06 / min combined audio; `gpt-realtime-mini` plans closer to ~$0.02 / min.	Avg phone demand: 1 five-minute AI call / 3 bookings ≈ $0.10	$3 / $10 / $25
Usage subtotal (30 / 100 / 250 bookings)			~$8 / $28 / $71

Direct OpenAI GPT Realtime Rate Card

These are direct OpenAI API prices for the active voice stack. The per-minute estimate above depends on talk/listen ratio, silence, cached context, and tool-call text volume, so reconcile it against the OpenAI usage dashboard after the first billing cycle.

Model	Audio input	Cached audio input	Audio output	Text input	Text output
gpt-realtime (gpt-realtime-1.5 pricing)	$32.00 / 1M tokens	$0.40 / 1M tokens	$64.00 / 1M tokens	$4.00 / 1M tokens	$16.00 / 1M tokens
gpt-realtime-mini	$10.00 / 1M tokens	$0.30 / 1M tokens	$20.00 / 1M tokens	$0.60 / 1M tokens	$2.40 / 1M tokens

OpenAI Transcription Add-On

Model	Use	Direct OpenAI price	Planning note
gpt-4o-mini-transcribe	Recommended call audit transcript	$0.003 / minute	~$0.50 / mo at 100 bookings if 1 five-minute AI call per 3 bookings
gpt-4o-transcribe	Higher-accuracy transcript fallback	$0.006 / minute	About 2x the mini transcript cost
whisper-1	Legacy/common baseline	$0.006 / minute	Useful for comparison, not the preferred admin default

All-In System Cost (estimate)

This is what running the automation platform itself costs each month — independent of revenue or payment processing.

Volume	Bookings / mo	Fixed	Usage	System total
Low	30	~$28	~$8	~$36 / mo
Typical	100	~$28	~$28	~$56 / mo
High	250	~$28	~$71	~$99 / mo

💳 Payment Processing Fees (separate — cost of doing business)

These fees apply any time a customer pays by card, whether the booking came through this automation, a manual phone quote, or a paper invoice. They are not a cost of the system itself — list them separately when comparing automation vs manual operations.

Processor	Channel	Rate	Per $300 booking	30 / 100 / 250 bookings
Square	Online (Checkout Links)	2.9% + $0.30	~$9.00	$270 / $900 / $2,250
Square	In-person (Tap-to-Pay on phone)	2.6% + $0.10	~$7.90	$237 / $790 / $1,975
Square	Manually keyed	3.5% + $0.15	~$10.65	$320 / $1,065 / $2,663
Typical scenario: 100% Square online checkout links				$270 / $900 / $2,250
Hybrid scenario: 50% Square online + 50% Tap-to-Pay				$254 / $845 / $2,113

Combined: System + Processing

Volume	Bookings / mo	System	Processing (Square online)	Combined
Low	30	~$36	~$270	~$306 / mo
Typical	100	~$56	~$900	~$956 / mo
High	250	~$99	~$2,250	~$2,349 / mo

Revenue vs Cost (offset analysis)

Assumes $300 average booking value. Net revenue = gross revenue − combined system & processing cost. Margins reflect operating costs only — performer pay, marketing, and overhead are separate.

Volume	Bookings / mo	Gross revenue	System cost	Processing	Net after costs	Cost as % of revenue
Low	30	$9,000	~$36	~$270	~$8,694	3.4%
Typical	100	$30,000	~$56	~$900	~$29,044	3.2%
High	250	$75,000	~$99	~$2,250	~$72,651	3.1%
Annualized at typical (100/mo)		$360,000	~$672	~$10,800	~$348,528	3.2%
Annualized at high (250/mo)		$900,000	~$1,188	~$27,000	~$871,812	3.1%

Bottom line: combined operating costs hold at roughly 3.1–3.4% of gross revenue across all volumes. Processing fees scale linearly with revenue (built into pricing), while system costs grow slowly — so margins improve as volume grows. The system pays for itself after a single $300 booking each month.

Notes & assumptions:

The system itself is cheap — under $100/mo even at 250 bookings. The big number is processing fees, which you'd pay regardless of how the booking was taken.
Square online checkout links: current default at 2.9% + $0.30. Square Tap-to-Pay is 2.6% + $0.10, about ~14% cheaper per transaction for in-person collections.
Hybrid recommendation: Square online checkout links for deposits and scheduled balances; Square Tap-to-Pay on a phone for day-of balances if the artist takes payment in person.
Average booking value assumed at $300. Higher-AOV bookings (packages, multi-artist events) increase absolute fees but the percentage stays flat.
SMS volume assumes the full automation flow: inquiry confirmation, quote, deposit link, deposit-paid receipt, T-3 balance reminder, balance-paid receipt, artist intro, day-after review request.
AI phone calls assume an avg of 1 inbound call per ~3 bookings (most bookings come via the website form, not phone).
Voice cost is now OpenAI GPT Realtime (single integrated speech-to-speech) instead of the old Cartesia STT + Sonic TTS + Groq LLM split. Single realtime API call, one OpenAI bill, and deterministic backend tools for pricing, availability, booking, transfer, and owner notifications.
Not included: Google Ads / Meta Ads spend (separate marketing budget), domain renewal spikes, OpenAI overage if call volume surges, transactional refunds, optional Square hardware (Reader $0 with software, Terminal ~$299 one-time).
To make this exact: after the next billing cycle, replace the unit-price estimates above with figures pulled from each provider's invoice (Vonage dashboard → Billing, Square → Reports → Fees, OpenAI usage dashboard → Realtime + transcription, Hetzner / DigitalOcean → Invoices).

🏗️ System Architecture

Data Flow

Customer Journey:
  Website Form, Bella Call, Manual Admin Entry, or AI Recommendation
      ↓
  FastAPI ingest → durable form_submissions row
      ↓
  Scheduling request booking
      ↓
  Admin guided review or AI-safe review package
      ↓
  Finalization/change gate validates assignment, price, travel, payment type
      ↓
  Explicit workflow event after final save only
      ↓
  Square link / Invoice PDF / Receipt PDF / manual action / notifications
      ↓
  Payment ledger + Scheduling status + Team calendar sync

Tech Stack

Website	Static HTML/CSS/JS, 775 SEO pages (642 city+service + 127 city hubs + 6 regional hubs)
Admin Portal	Vanilla HTML/CSS/JS SPA
Backend	FastAPI + SQLAlchemy + PostgreSQL Scheduling records
Workflows	N8N (self-hosted at n8n.optimus.systems) for delivery/payment side effects
Payments	Square hosted checkout links + Tap-to-Pay
SMS	Vonage Messages API
Voice AI	OpenAI GPT Realtime (`gpt-realtime`) — single speech-to-speech model in FastAPI WS bridge
Calendar	FastAPI Scheduling records with optional Team Microsoft/Google sync

🗺️ Architecture Diagrams

System Overview

A request can come from the website, Bella, a human admin, or a future AI operator. Only the finalization gate turns it into customer-facing payment, document, artist, or notification side effects.

Request SourcesWebsite form, Bella call, human admin, or future AI operator.
FastAPI IngestPersist durable form submission and Scheduling request booking.
Review PackageAdmin or AI receives missing checks, pricing, artist, and payment context.
Finalization GateIncomplete checks loop back to guided review before any side effects.
Finalize SnapshotBackend validates and stores the authoritative booking snapshot.

Workflow branches after finalization

SquareCreate hosted payment request, attach invoice PDF, update ledger from webhook.

Invoice / ReceiptGenerate invoice for money due; generate receipt only after payment posts.

ManualNo outbound payment yet; status stays visible for operations and audit.

Status Follow-UpCalendar, team, payment status, balance adjustments, and receipts update from the ledger.

Canonical Lifecycle

This shows the target booking states: form request, review, finalization, payment status, change review, refund review, and cancellation.

Form SubmissionRequest exists but has not been operationally reviewed.
Review In ProgressHuman or AI checks artist, base price, travel fee, and payment type.
Ready To FinalizeAll required confirmations are complete and backend-verifiable.
FinalizedSnapshot is locked for workflow dispatch and audit history.
Payment PendingSquare, invoice, or manual payment action has been requested.
Paid / Balance DueLedger shows deposit paid, balance due, or paid in full.

Material edit outcomes

Change ReviewArtist, additional artist, reschedule, price, or payment edits reset affected checks.

Refund ReviewCancellation or price decrease after payment requires refund or credit decision.

CancelledCancellation reason, notifications, and payment outcome are recorded before closure.

Finalization Gate

The green-arrow review cursor loops through missing checks. The pink save button is ready only after backend-verifiable checks are complete.

Open RequestLoad request, proposed booking, pricing, artist, travel, and payment context.
Find Next GapGreen arrow points at Assigned Artist, base price, travel fee, or payment type.
Confirm StepHuman or AI updates and confirms the highlighted requirement.
Ready SavePink rotating-beam button appears only when checks are complete.
Backend ValidateServer rejects stale or incomplete review packages and returns the next gap.
Dispatch WorkflowOnly final save triggers payment, PDF, artist, or notification workflows.

AI Operating Model

AI can prepare recommendations, but the backend remains the referee for assignment, price, travel, ledger math, and workflow dispatch.

1. AI asks FastAPIGET next review package with booking, form, payment, availability, and pricing context.

2. FastAPI reads PostgresReturns structured missing checks, recommendations, warnings, and candidate actions.

3. AI proposes changesSubmits artist, price, travel, schedule, or payment changes as a proposal, not side effects.

4. Backend validatesAssignment, price, travel, payment ledger, and stale package checks are enforced server-side.

5. AI finalizes when readyFinalize and Save writes snapshot and audit record only after all checks pass.

6. Workflow receives eventN8N or backend workflow sends payment request, invoice, receipt, artist update, or notice.

Change Review

Material edits after finalization move through change review, not direct side effects.

Finalized BookingExisting snapshot has already dispatched one or more workflows.
Material EditArtist, additional artists, time/date, cancellation, price, or payment changes are detected.
Reset Affected ChecksOnly fields touched by the change return to review, with prior values preserved.
Confirm ChangesHuman or AI must explicitly accept the recalculated operational and payment impacts.
One EventPersist audit record and trigger exactly one explicit change workflow event.

Change-specific checks

Artist ChangeRecheck assignment, availability, and team notification.

Additional ArtistsRecheck assignment, base price, travel fee, and payment total.

RescheduleRecheck availability, assignment, travel, payment due date, and customer notice.

CancelRequire reason, notification choice, payment status, and refund or credit decision.

Payment Ledger Rules

Once payment exists, all new payment asks are calculated from successful payments already received.

Confirm Final TotalUse the finalization snapshot or confirmed change review total.
Load PaymentsOnly successful, posted payments count toward the received total.
Calculate Dueamount_due_now = max(final_total - successful_payments_total, 0).
Calculate Overpayoverpayment_amount = max(successful_payments_total - final_total, 0).
Choose WorkflowRequest deposit, balance, adjustment, corrected link, refund review, or receipt.

Ledger outcomes

No PaymentRequest deposit or full amount based on payment type.

Deposit PaidRequest remaining balance only, never a duplicate deposit.

Total IncreasedRequest adjustment difference only.

Total DecreasedStart refund or credit review before customer-facing follow-up.

Square Hosted Payment Request

Square links are generated for the ledger-calculated amount due now and paired with invoice/receipt PDF history.

Admin or AIFinalize with payment_workflow = square.

FastAPICalculate amount_due_now from the payment ledger.

PDF GeneratorCreate invoice PDF with total, payment history, and remaining balance.

N8NReceives booking.square_payment_required.

SquareCreate hosted checkout link for amount_due_now.

CustomerReceives SMS or email with payment link and invoice PDF link.

Payment WebhookSquare posts result; N8N persists payment and status updates.

Receipt PDFGenerated only after successful payment posts.

Invoice and Receipt Path

Invoices request money; receipts prove money was received. Manual and AI flows must keep those separate.

Finalize Invoice PathBooking uses invoice_receipt workflow after final checks pass.
Generate InvoicePDF shows final total, payments already received, and remaining balance.
Send RequestOutlook email or SMS link sends the invoice to the customer.
Record PaymentManual payment or Square reconciliation creates a successful ledger entry.
Generate ReceiptReceipt PDF proves payment received and is sent or stored for audit.

📈 Scalability Plan

Executive Summary

Poppin' Partiez 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.

	Existing Services	New Services / Verticals
Existing Markets (6 TX metros)	Market Penetration Phase 1 — Saturate 127 TX cities. Bid harder on long-tail SEO + targeted Google Ads. Add hosted artist roster per region. Capture share from local solo artists.	Product Development Phase 2 — Add Corporate Events, School Districts, Festivals, Country Clubs verticals. Higher AOV ($800–$2,500) and recurring contracts. Same crew, new packaging.
New Markets (adjacent states / national)	Market Development Phase 3 — Replicate the TX template into OK, LA, AR, NM, then top 50 US metros. Each new region = clone the SEO factory + recruit 8–12 contractors.	Diversification Phase 4–5 — License the platform to other entertainment operators (white-label SaaS). Royalty + per-booking fee. Asset-light, software-margin business inside the entertainment shell.

Successful Square webhook confirmations now post the first entry automatically for scheduled POPN payments: Square Clearing is debited for service amount plus tip, Customer Deposits is credited for the service amount, and Tips is credited when Square reports a tip. Payout fees, refunds, disputes, and net Chase deposit matching remain later reconciliation work.

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.

Phase	Timeline	Focus	Bookings / mo	Avg AOV	Annual Revenue	Op Margin*
Phase 1 Optimize	Months 0–6	Saturate existing 6 TX metros; tighten ads ROAS to 5:1; grow performer roster to 25	100 → 150	$300	$540K	~28%
Phase 2 Verticalize	Months 6–18	Launch Corporate, Schools, Festivals lines; AOV lifts via packages	250 + 20 corp	$420 blended	$1.36M	~32%
Phase 3 Regionalize	Year 2–3	Expand to OK, LA, AR, NM (12 new metros). Clone SEO factory per state.	600 + 60 corp	$420 blended	$3.32M	~34%
Phase 4 Nationalize	Year 3–5	Owned-and-operated in top 25 US metros; centralized dispatch + AI phone	1,800 + 200 corp	$450 blended	$10.8M	~36%
Phase 5 Platform	Year 5+	License white-label platform to 50+ independent entertainment cos. Revenue = SaaS fee + booking %.	4,000 + 50 licensees	$450 blended	$26M+	~42%

*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).

🏷️ Vonage 10DLC Brand Checklist

Use this before resubmitting a brand verification. Vonage/TCR charges another review fee when brand details are resubmitted.

Brand type: Customer brand — used for Poppin' Partiez's own messaging traffic
Legal name: Must match tax/business records; use DBA/brand display only where requested
Tax ID/EIN and address: Must match business records exactly
Stock symbol/exchange: Leave blank or none for a private/non-public business; do not enter N/A, initials, or a guessed ticker
Common rejection: "Stock Symbol: Not a public company" means the brand was submitted with stock-market metadata and should be cleared before resubmission

Phase 1 · Months 0–6 · Optimize TX$540K

Phase 2 · Months 6–18 · Verticals$1.36M

Phase 3 · Year 2–3 · OK/LA/AR/NM$3.32M

Phase 4 · Year 3–5 · Top 25 US metros$10.8M

Phase 5 · Year 5+ · Licensed Platform$26M+

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.

Layer	Definition	Size	Our Share Target
TAM (Total)	U.S. event entertainment services (kids' parties, corporate events, school assemblies, festivals)	$36 B	—
SAM (Serviceable)	Face painting / balloons / caricature / glitter / bubble services in top 50 US metros — fragmented, served by solo artists	$2.8 B	—
SOM Phase 3	5-state TX-cluster footprint; Phase 3 target	~$220 M	1.5% ($3.3M)
SOM Phase 4	Top 25 US metros owned-and-operated	~$650 M	1.7% ($10.8M)
SOM Phase 5	Owned ops + licensed network covering top 100 US metros	~$1.4 B	1.9% ($26M+)

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.

Vertical	AOV Range	Cadence	Margin Profile	Phase
Kids' birthday parties (current)	$200 – $600	One-off (peak Sat/Sun)	Standard 30%	1
Corporate / company events	$800 – $2,500	Quarterly + holiday season	Premium 38% (lower CAC, B2B referrals)	2
School district contracts	$1,500 – $5,000	Recurring (PTA fairs, field days, end-of-year)	Premium 40% (low marketing, high LTV)	2
Festival / multi-day events	$3,000 – $15,000	Seasonal anchor (4–6/year)	Premium 35% (high gross, higher logistics)	2
Country clubs / annual contracts	$6,000 – $20,000	Annual retainer + per-event	Premium 42%	3
Theme parks / venue revenue-share	Variable	Daily ops	Standard 30% (rev-share contract)	3
Wedding receptions / Bar Mitzvahs	$600 – $2,000	Seasonal peak (May–Oct)	Premium 36%	2
White-label platform license	$8K–$15K MRR per licensee	SaaS recurring	Software 70%+	5

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.

Tier	Geography	Cities	Target Bookings / mo	Phase
Tier 0	Existing: DFW, Houston, Austin, San Antonio, Waco, Stephenville	127	250 (target)	1
Tier 1	TX expansion: El Paso, Lubbock, Amarillo, Corpus, McAllen, Tyler, Longview	+50	+150	2
Tier 2	Adjacent states: OKC, Tulsa, Shreveport, Little Rock, Albuquerque, Las Cruces	+80	+250	3
Tier 3	National core: Phoenix, Denver, KC, Nashville, Atlanta, Charlotte, Tampa, Orlando	+200	+700	4
Tier 4	Licensed network: 50 territories @ ~80 bookings/mo each (operator-managed)	+1,000	+4,000	5

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

Line item	Phase 1	Phase 2	Phase 3	Phase 4
Gross revenue	$300	$420	$420	$450
− Performer payout (50%)	−$150	−$210	−$210	−$225
− Processing (~3%)	−$9	−$13	−$13	−$14
− System cost / booking	−$0.56	−$0.40	−$0.30	−$0.20
− CAC (blended)	−$36	−$38	−$32	−$30
− Ops overhead (mgmt, insurance, supplies)	−$21	−$25	−$22	−$20
Contribution margin / booking	$83	$134	$143	$161
Margin %	27.7%	31.9%	34.0%	35.7%

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.

Phase 1 · Local TX28%

Phase 2 · TX + Verticals32%

Phase 3 · Multi-state34%

Phase 4 · National O&O (owned-and-operated)36%

Phase 5 · Licensed Platform42%+

Revenue Mix Evolution

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

Revenue line	Phase 1	Phase 2	Phase 3	Phase 4	Phase 5
Kids' parties (B2C)	100%	72%	62%	54%	40%
Corporate events	—	15%	16%	18%	14%
Schools / Districts	—	8%	10%	10%	8%
Festivals / Venues	—	5%	8%	8%	6%
Country clubs / Retainers	—	—	4%	6%	4%
Licensed platform (SaaS)	—	—	—	4%	28%

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.

Phase	Investment	Primary Use	Payback
Phase 1	$15K – $30K	Ad spend acceleration, performer recruiting bonuses, supplies inventory	~4 months
Phase 2	$60K – $120K	B2B sales rep (1 FTE), corporate sales collateral, district outreach, festival gear	~7 months
Phase 3	$300K – $600K	Per-state launch (4 states × ~$120K), regional managers, dispatch coordinator (1 FTE)	~10 months
Phase 4	$1.5M – $3M	National brand campaign, 25 metro launches, full ops team (~8 FTE), centralized warehouse	~14 months
Phase 5	$2M – $4M	Platform productization (multi-tenant SaaS), licensee onboarding, sales team, legal/franchise compliance	~18 months

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.

Risk	Severity	Mitigation
Performer supply shortage as we scale	High	Build a recruiting funnel (Indeed + art schools); standardize 1-day training; tiered payout to incentivize loyalty
Google Ads CAC inflation	Medium	SEO compounds across 642+ landing pages — own organic top-3 in target keywords; nurture repeat customers (target 25% repeat by Phase 3)
Quality drift across regions	High	Centralized SOPs in this admin platform; dispatch scoring; post-event review automation; mystery-shop audits
Saturation in core verticals	Medium	Vertical expansion (corporate, schools, festivals) is the primary hedge; each vertical has independent demand curve
Platform technology dependency (N8N, OpenAI, Vonage, Square)	Medium	Provider boundaries are isolated behind backend workflows and config. Voice and payment vendors can be swapped without changing the public website.
Regulatory / insurance (Phase 4–5)	Medium	Master GL policy ($2M aggregate) + per-territory riders; W-9 contractor model with clean 1099 audit trail; franchise legal counsel before Phase 5

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.

Year	Phase	Revenue	Op Margin	EBITDA	Cumulative Invested
Y1	1 → 2	$540K → $1.0M	28–30%	~$240K	$45K
Y2	2 → 3	$1.36M → $2.2M	32–33%	~$590K	$165K
Y3	3	$3.32M	34%	~$1.13M	$465K
Y4	3 → 4	$6.5M	35%	~$2.28M	$1.4M
Y5	4	$10.8M	36%	~$3.9M	$3.0M

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.

❄️ Seasonality & the Winter Trough

A seasonal trough is the predictable low point in a business's revenue cycle. Counter-cyclical revenue = a different income stream that peaks when the main one dips, smoothing total cash flow across the year.

The kids' party business has a sharp ~9-week trough that runs from the week after Christmas through the end of February. School holidays end, weather pushes events indoors, family discretionary spend drops post-holidays, and outdoor venues close. Without intervention, monthly bookings can fall 40–55% below summer peak during these three months only — March recovers fast and April onward is peak through October, with a strong spring surge in May. Q1 alone threatens artist retention and creates cash-flow strain on fixed costs.

The wrong answer is layoffs. Releasing trained artists in February means recruiting and re-training in March/April — costing 3–4 weeks of ramp time exactly when demand is exploding into the spring peak. Industry data on seasonal labor churn shows replacement cost of 1.5–2× annual contractor pay per lost artist (recruiting, vetting, training, lost goodwill, slower response times during ramp).

The right answer is counter-cyclical revenue. Build complementary lines that peak in Dec–Feb so artists stay engaged, paid, and ready for the spring surge. Below: a portfolio of options ranked by alignment with our existing assets (skills, brand, customer list, regions, automation platform).

Annual Demand Curve — Before vs After

Indexed bookings per month (100 = annual average). Grounded in three public data sources triangulated against our own 2025 booking history:

Google Trends for the U.S. search terms “face painter near me”, “balloon twister”, and “kids party entertainment” (rolling 5-year average). Search volume bottoms in Jan–Feb at ~45–60% of the May–Oct peak and recovers sharply in March.
U.S. CDC Vital Statistics birth-month distribution: ~9% of births fall in August–October vs ~7.3% in February. Since birthday parties cluster around the actual birth month, this drives a structural Q4 + spring peak and Jan–Feb dip in kids’ party demand.
Party City & Oriental Trading public earnings commentary consistently calls Q1 (Jan–Mar) their seasonal trough, with Q4 the peak — a pattern that mirrors at the venue/entertainer level.

Late December (post-Christmas), January, and February are the structural trough. March recovers, April → October is peak, and November/early-December gets a holiday-party bump.

Today (B2C only)

With counter-cyclical mix

Jan

Feb

Mar

Apr

May

Jun

Jul

Aug

Sep

Oct

Nov

Dec

Net effect: annual variance drops from a 3-to-1 peak-to-trough ratio to ~1.6-to-1. Cash flow becomes predictable; performer retention rises from ~60% to ~85% YoY.

Counter-Cyclical Revenue Portfolio

Each option ranked by asset reuse (1 = uses our existing artists/brand/regions/platform; 5 = mostly new build). Lower scores launch fastest with the least new investment.

Initiative	Peak Window	Asset Reuse	Est. Revenue Lift (per metro / month)	Why It Works
1. Holiday Pop-Up Events (Mall Santa supplemental, Christmas market face painting, NYE family party gigs, Mardi Gras, Valentine's school events)	Dec 1 – Feb 14	1 — same artists, same skills	$8K – $18K	Malls, markets, hotels actively pay $400–$800/day for face painters & balloon artists during holidays. Direct extension; just need a B2B sales motion targeting venues.
2. Indoor Birthday Venue Partnerships (trampoline parks, bowling alleys, indoor playgrounds, Chuck E. Cheese-style)	Dec – Feb (peak indoor)	1 — same artists, no weather risk	$5K – $12K	Indoor venues' add-on entertainment is usually thin. Become the preferred entertainment add-on (rev-share or per-event). Counter-intuitively the indoor birthday volume rises in winter as outdoor parks close.
3. Corporate Holiday Parties (office holiday events, family days, year-end employee appreciation)	Dec 1 – Jan 31	1 — overlaps Phase 2 vertical	$10K – $25K	Corporate budgets close in December; "kids welcome" company holiday parties are a growing trend. AOV $800–$2,500. Booked 4–8 weeks in advance.
4. Daycare & Preschool Curriculum Visits (weekly art / balloon-craft / sensory-bubble enrichment)	Year-round; peaks Jan–Feb when schools restart	2 — same artists, recurring contracts	$6K – $15K	Daycares pay $150–$300/visit for enrichment. 1 artist × 4 daycares × 2 visits/week × $200 = $1.6K/wk per artist. Recurring revenue, predictable cash flow.
5. Senior Living & Assisted Care Entertainment (holiday socials, monthly themed events)	Year-round; spikes Dec–Feb	2 — caricatures & balloons translate well	$3K – $8K	Activity directors at senior communities have monthly entertainment budgets; winter is their highest-need period (residents indoors). Caricatures & balloon flowers are universally loved across ages.
6. Winter Workshop Series (face-paint & balloon-twist classes for 8–14yo on weekends, in-home or at a leased studio)	Jan – Mar	3 — same artists, new format	$4K – $9K	Parents pay $35–$60/seat for 90-min workshops. Small space rental (~$500/mo) offsets via 4 classes × 12 kids × $45 = $2,160/weekend. Builds future customers (workshop kid → birthday booking).
7. School Spirit Week / Pep Rally / Field Day (in-school theme days, mascot-aligned face painting, glitter tattoos)	Jan – Mar	3 — same artists, B2B sales effort	$5K – $14K	Schools have ~$3K–$10K event budgets. Spring spirit days & fundraisers cluster in the Jan–Mar window. Booking 1 school = 6–10 events for the year.
8. Branded Merchandise / Subscription Box ("Poppin' Partiez Kit" — face paint set, balloon set, themed crafts mailed monthly)	Q4 gifting + Year-round	3 — leverages brand & customer list	$2K – $10K	Existing customer list is a warm market. $35/mo subscription × 200 subs = $7K/mo recurring at high gross margin. Cross-sells back into birthday bookings.
9. Indoor Bubble Show / Magic Mini-Show Production (40-min staged shows at libraries, community centers, malls)	Dec – Feb (school break programming)	3 — needs 1–2 trained performers	$3K – $7K	Libraries & rec centers pay $300–$800 per show during school breaks. Bubble Party is already a service line — productize into a ticketed/paid show format.
10. Wedding Reception Kids' Corner (face paint + balloons + glitter as add-on at Sat winter weddings)	Year-round; winter wedding niche grows	2 — same artists, B2B partnership	$3K – $7K	Partner with wedding planners for "kids' table entertainment" packages. AOV $400–$800 per wedding. Saturday slots that would otherwise sit idle.
11. Branded Photo Booth & Event Activation Rentals (themed backdrop + balloon arch + face-paint activation, run by 1 artist)	Year-round; holiday parties + winter weddings	3 — equipment investment ~$2K	$4K – $11K	Photo booth + entertainer combo charges $600–$1,200/event vs $400 for a solo artist. Same labor, 50% higher AOV. Equipment paid back in ~5 events.
12. Halloween / Day of the Dead / Easter Specialty Events (off-peak holiday clustering)	Late Oct + early Apr	1 — bridges shoulders	$6K – $14K	Already partially captured. Aggressive bookings push for Halloween parties (face paint = perfect fit) and spring egg hunts smooths the Sep–Apr curve.
13. Adjacent Business: Mobile Tax-Season Pop-Ups (Skip) (low alignment — mentioned for completeness)	Jan – Apr	5 — wrong audience, wrong skills	—	Listed only to document we evaluated it. Doesn't fit kids' entertainment brand. Don't pursue.

Recommended Winter Strategy (Year 1 — quick wins)

Pick the top 4 highest-asset-reuse plays. Together they target a ~$30K–$60K monthly revenue floor for Dec–Feb at Phase 1 volume — enough to retain the entire artist roster.

Play	Setup Effort	Time to First $	Dec–Feb Target
Holiday pop-up events (mall Santa, holiday markets, NYE)	2 weeks B2B outreach	~30 days	$15K – $30K
Corporate holiday parties (existing Phase 2 vertical, accelerated)	4 weeks (sales rep)	~45 days	$10K – $20K
Indoor venue partnerships (trampoline parks, bowling alleys)	3 weeks (5–10 partner contracts)	~30 days	$5K – $12K
Daycare / preschool weekly enrichment	4 weeks (district outreach + curriculum doc)	~60 days	$6K – $15K
Combined Dec–Feb run-rate (Phase 1 metro):			$36K – $77K / mo

Compare to a "naked" winter month at Phase 1: ~$13K–$20K (45–55 bookings × $300). The portfolio approach roughly triples winter cash flow while keeping artists employed.

Layoffs vs Counter-Cyclical: The Math

Per-metro comparison at Phase 1 volume. Assumes 12 contractor artists.

Strategy	Dec–Feb cost	Mar ramp-up cost	Mar–Apr capacity	Q1 + Q2 revenue impact
Layoff & Re-hire	$0 (no payroll)	~$18K (recruiting + 3-week ramp + lost bookings)	60–70% of normal	−$45K to −$75K (lost spring bookings, slow response, quality drift)
Counter-Cyclical Mix	~$8K marketing + ~$2K coordination	$0 (full crew ready)	100% from day 1	+$95K to +$165K (winter revenue + uninterrupted spring + retention bonus)

Net swing per metro per year: ~$140K–$240K in our favor. Plus the unquantifiable wins: artist loyalty, brand reputation as a "real job, not a gig," and recruiting leverage when scaling new metros (existing artists become trainers/refers).

The Compounding Advantage

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

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

Frontend Roadmap Parking Lot

Later Consideration Only

This item records the June 2026 frontend architecture review for later consideration. It is not part of the active Books, Scheduling, booking workflow, finance integration, or production-promotion planning slices. No framework migration should block current Dev-to-Prod work.

Surface	Current signal	Recommendation	Status
Admin app tooling	Admin shell is roughly 9.6k lines; lazy Admin modules are roughly 20.4k JS lines across 27 files.	Add Vite first as an Admin-only tooling/build layer, preserving FastAPI, nginx, auth, and the current static deploy contract.	Parked
Heavy Admin tabs	Books and Scheduling now behave like full applications with complex state, filters, exports, polling, and auth-aware API calls.	Pilot a framework inside one bounded Admin panel before any broad rewrite. React + Vite is the safest ecosystem choice; Svelte + Vite remains a lean compiled alternative.	Parked
Native Admin shell	No installed-app, offline-first, or native-device requirement is blocking current Admin work.	Consider Tauri only after the Admin Vite/framework pilot, and only for a concrete native need: offline queueing, local receipt/file workflows, native notifications, tray/global shortcuts, encrypted local storage, mobile device features, kiosk/desktop install, or a dedicated internal operations console.	Optional
Public/SEO site	Static pages and the SEO generator still fit the public site well.	Keep public pages static for now. Consider Astro later only if the 775-page SEO/content generator becomes hard to maintain or needs component islands.	Later
Full SSR app framework	FastAPI already owns APIs/auth, and the current hosting model is static-admin plus backend routes.	Do not adopt Next.js-style SSR unless future requirements need server-rendered app routes. It is heavier than the current problem asks for.	Defer

Evaluation Path

Phase 0: keep current vanilla Admin work moving; track pain points and duplicated state/render patterns.
Phase 1: create a small Admin-only Vite/TypeScript spike that can mount beside the existing Admin shell without changing production routing.
Phase 2: migrate one low-blast-radius Books subpanel or new Admin module first; verify deploy, auth headers, server-session cookie behavior, and rollback.
Phase 3: choose React or Svelte for new/high-churn Admin surfaces only after the spike proves lower maintenance cost.
Tauri proof of concept: only after the web Admin architecture is stable. Point it at Orion Dev APIs first, and verify Microsoft/Google OAuth redirects, signed server-session cookies, WebView behavior, updater/installers, and native permissions before any production consideration.
Phase 4: revisit Astro for the public SEO site only if generator/content maintenance becomes a larger cost than static simplicity.

💰 Individual Service Pricing

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.

⭐ Value Package Pricing

🚗 Travel & Fee Structure

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: Square hosted payment links sent via SMS

🎨 All Services

🗺️ Service Regions

📋 Booking Flow

BookingWorkflow Purpose

The BookingWorkflow is the control layer between a request and real-world side effects. A form, call, manual entry, or AI recommendation can create or update draft Scheduling data, but customer-facing payment links, invoices, receipts, artist messages, Team calendar projections, and cancellation notices only run from an explicit final save or confirmed manual action.

Current Dev behavior creates unassigned Scheduling requests from website forms, infers website-form shade acknowledgement from venue choice, keeps AI intake shade validation for outdoor requests, and runs the finalization gate before payment or invoice delivery. Change-review and AI-safe review packages use the same backend validation contract described below.

Request Sources

Source	What creates the request	Current/target behavior	Workflow side effects
Website Form	Public contact form → N8N → FastAPI form ingest	Durable `form_submissions` row, dedupe key, linked unassigned booking with `status="form_submission"`.	Owner/customer contact workflow may run, but payment/artist workflows wait for finalization.
Bella Call	OpenAI GPT Realtime bridge collects structured booking details	Call transcript and tool outputs become a booking request or recommendation package.	Bella can prepare the request; backend finalization decides if booking/payment workflows can run.
Manual Admin	Admin creates/edits a booking or uses Manual Actions	Scheduling edits can save as draft data; Manual Actions can send a deliberate payment, invoice, receipt, corp-file, or schedule action with an audit reason.	Only the selected manual action or final save emits a workflow event.
AI Placeholder	Future AI operator receives review package	AI proposes artist, price, travel, payment type, and next action; FastAPI validates every check.	No bypass. AI uses the same finalize/change endpoint and audit trail as a human.

End-to-End BookingWorkflow

#	Step	Trigger	Action	Owner
1	Capture	Website, phone, manual admin, or AI	Persist the raw context first: form row, call transcript, admin draft, or review package.	FastAPI + N8N
2	Request	Enough structured event details exist	Create or update a Scheduling request with customer, service, date/time, city, quote, travel, deposit, and balance fields.	FastAPI
3	Review	Human or AI opens the booking	Load booking details, availability, pricing, payment ledger, warnings, and missing checks into a review package.	Admin UI / AI
4	Confirm	Checklist steps are reviewed	Confirm assigned artist, base price, travel fee, and payment type. The green arrow points at the next missing check.	Human or AI proposal
5	Finalize	All required checks pass	The pink save button becomes ready. Backend revalidates the checklist, payment ledger, and policy constraints.	FastAPI
6	Dispatch Event	Finalize/change save succeeds	Emit one explicit event such as `booking.square_payment_required`, `booking.invoice_required`, `booking.rescheduled`, or `booking.cancelled`.	FastAPI
7	Deliver	Workflow event is accepted	Send Square links, invoice PDFs, receipts, SMS/email notices, artist updates, or manual action logs.	N8N / Manual Actions
8	Reconcile	Payment posts or manual payment is recorded	Update payment ledger, calendar color, document history, Scheduling status, and Team calendar projection.	FastAPI

Lifecycle States

form_submission
  → review_in_progress
  → ready_to_finalize
  → finalized
  → payment_pending / deposit_paid_balance_due / paid_in_full

finalized or paid booking
  → change_review when artist, time, price, travel, payment type, or cancellation changes
  → confirm affected checks
  → Confirm Changes & Save
  → explicit workflow event

The full source architecture, diagrams, scenario matrix, and rollout phases are documented in BOOKING-WORKFLOW-ARCHITECTURE.md.

Workflow Event Names

Event	Meaning	Typical side effects
`booking.finalized`	Request became an operational booking.	Team/admin status, first payment action.
`booking.square_payment_required`	Square hosted link should be generated.	Square link, invoice PDF, SMS/email delivery.
`booking.invoice_required`	Non-Square invoice should be generated/sent.	Invoice PDF, Outlook/SMS delivery.
`booking.receipt_required`	Payment was received or manually recorded.	Receipt PDF, payment status update.
`booking.assignment_changed`	Artist assignment changed.	Artist notifications, Team calendar projection.
`booking.additional_artist_added`	Additional artist assignment changed.	Multi-artist projection, pricing/payment review.
`booking.rescheduled`	Date/time/duration/location changed.	Availability recheck, notifications, projection update.
`booking.cancel_requested` / `booking.cancelled`	Cancellation needs review or was approved.	Stop reminders, notify parties, refund review.
`booking.payment_adjustment_required`	Confirmed total exceeds successful payments.	Difference-only Square or invoice request.
`booking.refund_review_required`	Successful payments exceed total or cancellation needs payment decision.	Manual refund/credit decision queue.

✅ Finalize & Changes

Operator Sequence

Open a white/glowing Needs Assignment request or an existing booking with a material change.
Review the backend-generated package: customer details, services, city/address, date/time, quote, payment ledger, availability, and warnings.
Follow the bouncing green arrow to the next required check. Confirm only after the visible value is correct.
When all checks pass, the top pink save button becomes ready with the rotating beam.
Use Finalize and Save or Confirm Changes and Save. That single save writes the audit snapshot and triggers the selected workflow event.

Draft field updates may save booking data, but draft edits must not send customer payment links, invoice PDFs, receipt PDFs, artist notices, or cancellation messages.

Required Confirmation Checks

Check	Required before final save	Reset when...
Assigned Artist	Primary artist is selected, available, skill-matched, and region-valid.	Artist, service, date/time, duration, region, or staffing changes.
Base Price	Service/package price is reviewed or overridden with a reason.	Service, duration, guest count, artist count, discount, or manual price changes.
Travel Fee	Travel amount is confirmed after city/address/region/artist-base logic.	Address, city, region, assigned artist, or travel override changes.
Payment Type	Square, Invoice/Receipt, or Manual/No payment request yet is selected.	Total, due amount, balance state, or payment process changes.

The UI should guide one active check at a time with a bouncing green arrow. When all checks are confirmed, the pink top-level save button gets the rotating beam and becomes the only action that can trigger payment or notification workflows.

Reset Rules

Edited field or decision	Checks reopened	Why
Artist, service, date, time, duration, region	Assigned Artist, Availability	The current artist may no longer match skills, region, or open time.
Service, duration, guest count, package, discount, artist count	Base Price	The quoted service amount may no longer match the booking.
Address, city, region, assigned artist, travel override	Travel Fee	Travel may depend on distance, region, and artist base location.
Total, amount due, payment process, refund/credit decision	Payment Type	Square, invoice, manual, or no-request workflows may need a different action.
Customer notification, artist notification, cancellation reason	Change-specific checks	Post-finalization changes need explicit side-effect choices.

Change Review Edge Cases

Change	Checks to reopen	Workflow after save
Change Artist	Assigned artist, availability, team notification, and travel if artist-base travel changes.	Notify removed/new artist, update Team projection, preserve payment unless total changes. Event: `booking.assignment_changed`.
Add Artists	Assignment, base price, travel fee, and payment type if total changes.	Create/update assignment rows, recalc total/deposit/balance, request difference only if payment exists. Event: `booking.additional_artist_added`.
Reschedule	Availability, assignment, customer/team notification, and price/travel/payment when affected.	Update Scheduling, Team sync, balance timing, and payment request or invoice if amount changes. Event: `booking.rescheduled`.
Cancel	Cancellation reason, customer notification, artist notification, and payment/refund decision.	Stop future reminders, mark projections cancelled, notify parties, and route refund/credit review when money exists. Event: `booking.cancelled` or `booking.cancel_requested`.

Audit Snapshot

{
  "booking_ref": "POPN-Poppy-Crown",
  "change_type": "reschedule",
  "changed_by": "human:admin@example.com",
  "actor_type": "human",
  "confirmed_checks": {
    "assigned_artist": true,
    "base_price": true,
    "travel_fee": true,
    "payment_type": true,
    "customer_notification": true
  },
  "payment_ledger": {
    "confirmed_total": 250,
    "successful_payments_total": 60,
    "amount_due_now": 190,
    "overpayment_amount": 0
  },
  "workflow_event": "booking.rescheduled"
}

AI audit entries should also identify the model/agent and whether a human approved the action.

🧰 Manual & AI Workflows

Manual Actions Tab

Manual Actions exists for deliberate human interventions. It should not be treated as a shortcut around the booking ledger or finalization rules. Select the booking/form/call context first, preview the action, add an internal reason, then send or log the action.

Manual mode	Use when	Must include	Workflow/audit result
Payment Request	Customer needs a one-off Square request for deposit, balance, add-on, adjustment, tip, damage, fee, or custom amount.	Amount, recipient, customer description, internal reason, optional existing Square link/reference, invoice PDF when appropriate.	Prepared/send log plus optional Square request; booking total impact is explicit.
Invoice	Customer, school, company, or city needs a Square-link invoice or non-Square check/wire invoice.	Recipient, invoice type, initial/payment amount, organization/terms for non-Square, internal reason.	Invoice PDF generated and optionally sent; document history tracks active invoice.
Receipt	Payment was received outside automated Square webhook flow or a receipt needs regeneration.	Payment type, method, reference, service amount, tip amount, remaining balance, internal reason.	Receipt PDF generated; optional payment reconciliation updates booking paid state.
Schedule Override	Admin needs to check availability, log a schedule exception, or reconcile a booking date/time/service/performer.	Date, time, duration, services, region, performer id when selected, reason.	Availability check and schedule action log; DB update only when explicitly selected.
Send Corp Files	Purchasing/HR/AP requests W-9 or insurance documents.	Recipient email, organization, requested files, message, internal reason.	Corporate document send/log, separate from invoices and receipts.

Manual Workflow Rules

Manual actions must attach to the selected booking, form, or call context whenever possible.
The internal reason is required because manual sends bypass some automated decision points.
Payment request amounts should still come from the backend ledger when the booking has payments; use custom amounts only with a reason.
Invoices request money. Receipts prove money was received. Do not use a receipt as a payment request.
Manual payment reconciliation must update the payment ledger before calendar colors or balances are trusted.
Manual schedule override can log and preview first; it should update booking fields only when the checkbox is selected.

AI Placeholder Workflows

Bella and future AI operators should use placeholders until the backend finalization endpoint exists. The placeholder workflow prepares structured recommendations and warnings, then either asks a human to approve or calls the same validated endpoint once available.

Placeholder	AI can prepare	Backend or human must decide
`ai.booking_review_requested`	Summarize form/call details, identify missing fields, recommend next question.	Whether enough data exists to create or update a Scheduling request.
`ai.booking_finalization_proposed`	Recommend artist, base price, travel fee, payment type, and customer copy.	Availability, price/travel math, policy checks, final save authorization.
`ai.payment_adjustment_recommended`	Explain why an adjustment is due after price, artist, duration, or service changes.	Ledger amount, Square/invoice dispatch, refund/credit review.
`ai.cancellation_review_recommended`	Collect reason, customer preference, event/payment context, and suggested next message.	Cancellation approval, artist notification, refund/retain decision.
`ai.manual_action_draft`	Draft a manual payment, invoice, receipt, schedule override, or corp-files request.	Human preview/send until strict backend rules allow autonomous dispatch.

AI Review Package Shape

{
  "booking_ref": "POPN-Poppy-Crown",
  "finalization_status": "review_in_progress",
  "required_checks": ["assigned_artist", "base_price", "travel_fee", "payment_type"],
  "next_required_check": "assigned_artist",
  "recommended_artist": { "performer_id": "...", "reason": "available, skill match, nearest region" },
  "quote": { "base_price_dollars": 175, "travel_fee_dollars": 25, "total_price_dollars": 200 },
  "payment_ledger": { "successful_payments_total": 0, "remaining_balance": 200 },
  "warnings": []
}

The frontend and AI can display this package, but FastAPI remains the source of truth for final validation and workflow dispatch.

💳 Payment Flow

Payment Ledger Rule

amount_due_now = max(confirmed_final_total - successful_payments_total, 0)
overpayment_amount = max(successful_payments_total - confirmed_final_total, 0)

Once a deposit or final payment exists, the system does not ask for another deposit. It applies successful payments to the updated final total and requests only the remaining balance or adjustment difference.

Successful payments include settled Square webhook records and approved manual reconciliations. Pending links, drafts, failed payments, and voided requests do not count as paid.

Ledger Examples

Scenario	Total	Successful payments	New request	State
New booking, no payment	$200	$0	$60 deposit or selected full amount	`payment_pending`
Deposit paid, price rises	$250	$60	$190 balance	`deposit_paid_balance_due`
Paid in full, price rises	$250	$200	$50 adjustment	`adjustment_due`
Paid in full, price drops	$180	$200	$0; flag $20 refund/credit review	`overpaid_refund_review`
Cancel after deposit	$200	$60	$0; require refund/retain decision	`refund_review`

Square, Invoice, and Receipt Scenario Matrix

Scenario	Document/workflow	Amount due	Required history
New Square deposit	Invoice PDF with Square link	Deposit or selected full amount	No prior payments.
Deposit paid, balance due	Updated invoice/balance PDF	Remaining balance only	Deposit line with date, provider, and reference.
Paid in full, adjustment due	Adjustment invoice PDF	Difference only	Deposit/final payments already received.
Overpaid after change	Credit/refund review document	$0 due	Payment history plus overpayment amount.
Manual invoice	Invoice PDF	Remaining balance or full amount due	Any prior Square/manual payments.
Payment received	Receipt PDF	$0 due unless balance remains	Payment method, amount, date, and reference.
Cancellation with payment	Cancellation/refund review	$0 due	Payments received and refund/retain decision.

Square Hosted Payment Request

Admin or AI finalizes with payment_workflow="square".
FastAPI calculates amount_due_now from the payment ledger.
FastAPI/PDF layer generates an invoice PDF with services, travel, updated total, prior payments, and balance/adjustment due.
N8N receives booking.square_payment_required and creates a Square hosted checkout link for the ledger amount only.
SMS/email delivery includes the Square link and invoice PDF link when available.
Square webhook posts payment status back; FastAPI updates the ledger and generates a receipt PDF for successful payments.

Invoice/Receipt Path

Path	When used	Important distinction
Invoice PDF	Customer should pay by Square link, check, ACH, wire, or approved manual path.	An invoice requests money. It must show total, previous payments, and amount still due.
Receipt PDF	Payment posts from Square or is manually recorded.	A receipt proves payment was received. It must show method, amount, date, reference, and remaining balance if any.
Adjustment Invoice	Final total increases after deposit or full payment.	Request only the difference; do not repeat deposit language.
Refund/Credit Review	Final total decreases below successful payments or booking cancels with money received.	No payment link. Human or strict policy rule decides refund, credit, or retain.

Document Rules

Square payment requests: Hosted checkout link amount is the backend-calculated amount due now. The invoice PDF includes the Square link and payment history.
Invoice PDFs: Show services, travel, updated event total, payments already received, and remaining balance or adjustment due.
Receipt PDFs: Generate only after payment is posted or manually recorded. Show payment method, amount, date, reference, and remaining balance if any.
Frontend and AI: Never supply trusted paid-to-date math. FastAPI queries payment records and computes the ledger.
Manual Actions: Manual invoices and receipts must use the same ledger fields and write document/payment activity for audit.

💬 SMS Communication Workflows

⚙️ Workflow Events

💳 Square Payments

Setup

Create or connect the Square seller account for each region owner
Add the Square access token and location ID in Integrations → Payment Accounts
Assign each sales region to the correct Square account in Notifications → Sales Region
Use Square hosted checkout links for deposits, balances, and adjustment differences; use Tap-to-Pay when collecting in person

Payment Link Flow

N8N creates Square hosted checkout links with amount, description, region account, and booking metadata. Square collects card data on its hosted page, keeping the admin portal and workflows out of PCI-sensitive card handling. For updated bookings, the link amount is the backend ledger balance due, not a second deposit.

Updated Invoice PDF

Every Square request should have an invoice PDF or message body that shows the updated event total, payments already received, and the remaining balance or adjustment due. If the booking is overpaid, do not send a Square link; route it to refund/credit review.

Square Request Types

Request type	Source	Amount rule	Follow-up
Initial payment	Finalize new Square booking	Deposit amount or full amount selected at finalization.	Square webhook records deposit/full payment and generates receipt.
Remaining balance	Balance due after deposit	`confirmed_final_total - successful_payments_total`.	Receipt after payment; calendar turns paid when covered.
Adjustment	Price/service/artist/time change after payment	Difference only. Never resend the deposit.	Adjustment invoice and receipt history show original payments.
Manual payment request	Manual Actions tab	Human-entered amount with reason, ideally backed by ledger preview.	Manual action log; optional invoice PDF link.
Tip/add-on/damage/fee	Manual Actions tab	Standalone or booking-total-impact mode selected explicitly.	Audit notes explain whether it changes booking total.

Square Safety Rules

Square hosted pages collect card data; Admin, AI, and N8N should never ask for or store raw card numbers.
Square webhooks must validate authenticity before changing paid state.
Unpaid or obsolete payment links do not count as successful payments.
When a booking changes after a link is sent but before payment, obsolete the old request and issue a corrected request.
When money already covers the booking total, do not send another Square link; produce a receipt or refund/credit review instead.

📱 Vonage Integration

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

🤖 AI Phone Agent & Phone Routing

Overview

Bella is the GPT Realtime voice agent that handles inbound calls on +1 (972) 777-6725. She answers availability questions, quotes prices, collects booking details, creates booking requests, can cancel or escalate within policy, and can transfer callers to team members via supervised routing.

Capabilities

Inbound: Answer availability questions, quote prices, take booking details, check calendar
Booking: Create Scheduling requests now; future finalization uses the same review package and backend validation as Admin
Pricing: Real-time quotes for all services and durations (1-8hr events)
Transfer: Supervised routing — rings performers by priority group and requires press-1 acceptance
Placeholder workflows: Recommend finalization, adjustment, cancellation, or manual action drafts without bypassing backend validation

AI Workflow Boundaries

AI action	Allowed now	Requires backend gate / human approval
Collect booking details	Ask one question at a time, summarize service/date/time/city/customer details.	Final booking activation and payment dispatch.
Quote pricing	Use backend quote/pricing tools; mention estimate with clear assumptions.	Manual override, discount, or non-standard travel.
Recommend artist	Use availability and skill-match data in the review package.	Final assignment if availability, skill, region, or override checks fail.
Cancellation/escalation	Collect reason and notify manager when policy says escalate.	Refund/credit/retain decision unless strict rules cover it.
Payment action	Explain next step and prepare recommendation.	Square link, invoice, receipt, refund review, or manual send until validated.

📞 Phone Routing Modes

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

Mode	Behavior
⏸️ Off	Bella handles calls normally but cannot transfer. No supervised routing available.
🤖 Normal	Full AI conversation. Bella transfers only when the customer asks or she decides to escalate.
📵 Bypass AI	Skip Bella entirely. All callers go straight to supervised routing.
🐛 Debug	Only calls from performer phone numbers talk to Bella. Everyone else skips Bella and rings the configured On Call performer.

🔔 Supervised Routing

When a call is transferred without a named artist, the system screens team members before connecting the caller:

On Call performer rings first (if set) — covers ALL regions
Regional priority performers ring in order (lower number = rings first)
Performers outside working hours are skipped (if "Respect working hours" is enabled)
On Call and each regional priority group ring for the configured Ring Seconds; same-priority performers ring together and first press-1 accept wins
If nobody accepts, Bella resumes the conversation and offers to take a message

How to Configure

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

🔧 Technical Details

Platform: OpenAI GPT Realtime bridge in FastAPI
Voice: Marin (GPT Realtime speech-to-speech)
Bridge: /api/popn/voice/gpt-bridge/{slug}
Phone: +1 (972) 777-6725 (Vonage Voice API)
Transfer: Direct named transfer or supervised press-1 routing via Vonage Voice API
Deploy: Rebuild the FastAPI backend container

🌐 Landing Pages

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

📄775Total Pages

🏙️127Cities

🎨6Services

🗺️6Regions

🔥 Regional Hero Pages

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

Region	URL	Cities
🤠 Dallas-Fort Worth	/dfw-tx	27
🚀 Houston Metro	/houston-tx	20
🎸 Austin Metro	/austin-tx	20
🌵 San Antonio Metro	/san-antonio-tx	20
⭐ Waco Area	/waco-tx	20
🐎 Stephenville Area	/stephenville-tx	20

Core Service Pages

Page	URL
🏠 Homepage	PoppinPartiez.com
🎨 Face Painting	/face-painting
🎈 Balloon Twisting	/balloon-twisting
✏️ Caricatures	/caricatures
✨ Glitter Tattoos	/glitter-tattoos
🫧 Bubble Party	/bubble-party
📜 Privacy Policy	/privacy-policy
📜 Terms & Conditions	/terms-and-conditions

📅 Calendar Color Legend

Payment Status Colors

Calendar events automatically change color as payments are received:

Color	Status	Meaning
⚪ White / Glow	Needs Assignment	Form submission request needs finalization before customer/payment workflows run
🟠 Tangerine	Unpaid	New booking — no payment received yet
🟡 Banana	Deposit Paid	30% deposit received, balance still pending
🟧 Orange / Striped	Adjustment Due	Booking changed after payment; customer owes only the difference
🟢 Sage	Fully Paid	All payments received (deposit + balance, or full upfront)
🔴 Red / Gray	Cancelled / Refund Review	Booking is cancelled or successful payments exceed the confirmed final total

How It Works

Unassigned form submissions display as white glowing Needs Assignment request blocks until finalization.
Finalized bookings use payment ledger status to decide whether they are unpaid, balance due, adjustment due, paid in full, or refund review.
Manual Actions can create payment/invoice/receipt activity, but the ledger must be reconciled before the color is trusted.
AI placeholder recommendations should not change colors directly; the color changes only after the backend save/payment reconciliation.
When Square confirms a payment event, the POPN - Square Event Handler N8N workflow persists payment state; Scheduling color derives from booking/payment status.
Payment status, pricing, and Square tips are visible only to owners and regional managers in the calendar description (artists see event details only)
Manual/replayed payment updates should use the same Square event path documented in BOOKING-AUTOMATION-SYSTEM.md

📊 Books & Finance Operations

Purpose

The Books tab is the finance command center. Owners see it by default, and non-owner accounts can be granted Books from Users & Access. It should make business money easy to understand for non-accountants while preserving an accounting-grade backend design for tax, payroll, bank reconciliation, owner distributions, and K-1 support.

Plain-English UI:
Money In → Money Out → Money Set Aside → Money Owed → Money Available → Owner Payouts

Accounting engine:
Chart of accounts → Double-entry ledger → Reconciliation → Period close → Tax packets

Source docs: BOOKS-Finance-Operations.md is the comprehensive finance operations brief. BOOKS-TAB-ARCHITECTURE.md is the shorter implementation companion.

Current Dev Slice

Area	Status	Notes
Books tab	Live in Dev	Loaded from `admin-portal/modules/books/index.js`. Owners always see it; non-owner access is off by default and can be explicitly granted in Users & Access.
Data source	Read-only	Uses existing Scheduling bookings endpoint for initial KPIs/charts/workbench, including side-by-side estimated EBITDA and net income plus Cash Flow Scheduled/Settled/Variance views and a Regional Manager distribution tracker fed by statement periods plus paid/posted regional Expense Inbox support.
Finance backend	Source started	`/api/books/*` now has finance scopes, chart-of-accounts, periods, settings, audit events, balanced journal-entry routes, ledger reports, statement close/export routes, expense inbox review routes, private receipt attachment routes, and payroll tax filing packet/submission tables. Bank feeds, UI ledger posting, provider money movement, and tax API transport are still off.
Payroll configuration	Internal engine seed	Books Settings stores fictitious internal payroll engine employer/tax defaults for `Poppin' Partiez Inc`, re-shows W-2 employee setup from Users & Access plus linked Performer data, reads the editable Regional Manager W-2 hourly rate from the Performer section, and captures full SSN/TIN only through encrypted write-only backend secrets.
Payroll prerequisites	Metadata only	Worker IDs use one shared sequence across W-2 and 1099 records, so `W2-1` and `1099-1` cannot both exist. Contractor 1099 definition fields prepare W-9/EOY form data without moving money.
Payroll review	Manual payroll-ready Dev slice	Books Payroll mode is split into category buttons for Overview, Forms, Reviews, W2-Runs, Contractors, Taxes, Managers, and Distributions so operators can work one payroll surface at a time. It can generate cadence-based Regional Manager W-2 and Contractor 1099 review batches, hold/exclude/adjust review lines with reasons before approval, remove draft batches, submit them for approval, and approve them. Regional Manager W-2 pay uses managed event hours times the linked Performer W-2 rate; remaining manager-side dollars are distribution capacity. Approved W-2 review batches can become payroll runs, calculate tax/net-pay previews, be approved, prepare a CSV export for an outside payroll provider, and record external paid confirmation with locked pay-stub metadata, payroll-tax liability notes surfaced in Team Pay, and refreshed draft payroll tax packets under Taxes. Contractor batches separately support W-9 gating, approval, CSV/check-register export, external payment confirmation, and 1099 workpapers. Regional Manager Period Statements consolidate W-2 wages, distribution capacity, expense-support reserves, expense activity, remaining support, overage warnings, and source IDs for owner review. Payroll Tax Filings now generate IRS 941, EFTPS deposit, TWC wage report, IRS 940, W-2/W-3, and 1099-NEC/1096 packets from paid runs, allow draft packet deletion before review, require CPA/admin review and approval, and record direct portal/API submission attempts with confirmation/rejection status. The Distributions work area now separates owner and Regional Manager distribution decision flows from Manager statements/support. Books still does not submit payroll-provider payments, file tax returns automatically, post payroll/tax ledger entries, or move money; tax API providers stay blocked until configured.
Security	Finance scopes	Backend scopes include `finance:view`, `finance:manage`, `finance:approve`, and `finance:admin`. Books is grantable in Users & Access, defaults off for non-owners, and owner accounts always retain access.

Finance Build Plan

This build-plan reference now lives in Docs instead of Books Current Status. Payroll tax packet controls are complete in Dev; bank feeds and annual/correction tax packets are still planned work.

Status	Area	Boundary
Complete in Dev	Scheduling revenue read	Books reads Admin/Scheduling booking and payment state for KPI, projection, and payroll source workpapers.
Complete in Dev	Double-entry ledger foundation	Finance accounts, periods, audit events, balanced journal routes, report skeletons, and approved-expense posting paths exist. Broader automated posting from every money event is still expanding.
Complete in Dev	Receipt inbox and expense approval	Manual/email receipt intake, private file metadata, AI suggestions, review state, approval controls, and human-before-posting flow are live in Dev.
Complete in Dev	Payroll tax packets	IRS 941, EFTPS deposit, TWC wage report, IRS 940, W-2/W-3, and 1099-NEC/1096 packets can be generated from paid source records, reviewed, approved, downloaded as CSV, and marked with official portal/API submission outcomes. W-2 paid confirmation auto-refreshes regular W-2-related draft packets, and draft packets can be deleted before review.
Complete in Dev	QuickBooks / TXF file interchange	QuickBooks Trial Balance, Chart of Accounts, and General Ledger CSV imports can be staged/mapped with gated posting. Sealed statements can download file-only QuickBooks Trial Balance CSV and TXF-style Schedule C totals exports from frozen statement lines. QuickBooks API push, IIF export, real TurboTax import verification, tax filing, and money movement remain off.
Planned	Bank feeds	Choose a Chase-compatible read-only provider, add encrypted credentials/link flow, account mapping, transaction import jobs, idempotency, CSV/PDF statement fallback, and reconciliation UI.
Planned	Chase payment batches	Only after feed/reconciliation is stable: draft batches, line review/edit/hold, authorized human approval, final submit confirmation, provider response capture, void/return handling, and reconciliation back to imported Chase activity.
Planned	Annual and correction tax packets	1120-S, K-1 worksheets, Texas franchise/public information, Form 941-X, TWC corrections, government receipt uploads, and final PDF packet storage.
Blocked until configured	IRS/EFTPS/TWC API transport	Direct API providers intentionally fail closed until credentials, provider enrollment, request schemas, validation rules, and audit/confirmation handling are configured.
Production pending	Payroll tax packet promotion	Local and Orion Dev validation passed. Production deployment and a real-period CPA smoke test still require explicit approval.

Capability Map

Capability	What it does	Implementation direction
Overview	Cash, revenue, reserves, open balances, owner payout guardrail.	Dashboard cards and charts from ledger summaries.
Revenue / Money In	Square payments, deposits, final balances, refunds, future event deposits, revenue by region/service.	POPN payment workflows stay the real-time payment-event source. Square API activity pulls are still needed for payments, refunds, fees, disputes/chargebacks, payout batches, payout entries, locations, and audit detail.
Expenses / Money Out	Supplies, travel, ads, insurance, software, phone, professional fees, performer costs.	Expense Inbox now captures manual/email review items with sender, target domain, region, category, receipt file metadata, and AI suggestion metadata; bank feeds come later.
Bank Feeds	Pull transactions from bank/card accounts.	Chase should start as read-only feed import through Plaid, Akoya, Finicity, MX, or Teller-style coverage; encrypted credentials only with CSV/PDF statement fallback, account mapping, and historical start date. Full Chase payment/transfer batches can come later only with exact batch preview, line review, human approval, final submit confirmation, provider response capture, and reconciliation back to Chase activity.
Reconciliation	Match bank transactions to bookings, Square deposits, payroll, receipts, taxes, distributions.	Confidence scoring, manual override, audit trail.
Payroll & Contractors	W-2 wages, payroll liabilities, contractor payouts, W-9/1099 review.	Payroll provider/export integration after ledger foundation.
Owner Distributions	Track owner payouts separately from expenses.	Equity ledger with approvals and safe-distribution calculations.
K-1 / Owner Packets	Shareholder basis, distribution statement, final K-1 packet, TurboTax entry worksheet.	Year-end tax packet generated from closed ledger periods.
Reports & Exports	P&L, balance sheet, cash flow, trial balance, CPA/TurboTax/Texas/IRS workpapers.	CSV, Excel/PDF packets, and JSON ledger backup/export.
Current Projections	Project week, month, quarter, and EOY from current schedule/run-rate.	No strategic assumptions; just current booked/collected activity extrapolated.
Forecast Lab	Model future growth by changing regions, hires, ad spend, CAC, AOV, margin, pricing, tax reserve, and distribution assumptions.	Driver-based scenario planning separated from current-status reporting.

Report Examples

These examples show the intended report shape. Current Dev report rows are sparse until more journal entries are posted; final report totals must come from the double-entry ledger.

Report	Example output	Checks
Trial Balance	`1000 Checking Dr 7,810` `2000 AP Cr 395` `4000 Event Revenue Cr 8,950`	Total debits must equal total credits before any report is trusted.
Profit & Loss	`Revenue 8,950` `Expenses 3,527.50` `Net Income 5,422.50`	Revenue and expenses come from posted ledger lines, not modeled Scheduling totals.
Balance Sheet	`Assets 9,360` `Liabilities 2,795` `Equity 6,565`	`Assets - Liabilities - Equity = 0`.
General Ledger	`2026-05-25 expense_inbox Dr 5900 39.50 / Cr 2000 39.50`	Every report total should drill down to journal lines and source documents.
Cash Flow	`Beginning Cash 4,500` `Net Operating Cash 3,630` `Ending Cash 7,130` `Manager: W-2 separate from capacity`	Explains cash movement separately from accrual net income, and shows Regional Manager payout, W-2 wages, distribution capacity, elected distribution, and region-period operating costs without combining the buckets.
Regional Waterfall	`DFW basis 10,000` `Manager pool 9,500` `W-2 @ linked rate first` `Distribution capacity after W-2` `Election: distribution vs expense reserve` `Owner pool 500`	Manager-side dollars split into W-2 wages, elected distribution capacity, expense support reserve, and unallocated business funds, capped by realized regional proceeds and separate from the all-up owner pool.
Shared Region Waterfall	`Austin basis 8,000` `Manager pool 7,200` `2 managers = 3,600 each`	The region percentage is the total manager-side pool; shared managers split it evenly unless split weights are added later.
Owner Distribution Guardrail	`Cash 25,000 - reserves 19,750 = safe pool 5,250`	Tax reserve, payroll reserve, deposits liability, refund reserve, and operating cushion come before owner payouts.
Expense Inbox	`Kirkland Municipal Court 39.50 corp 5900 ai_reviewed`	AI suggests. Human approves. Posting creates balanced AP journal entries.
Tax Reserve	`Taxable income 18,000 * 18% = reserve 3,240`	Reserve calculations are planning aids until CPA review and posted tax entries exist.

Current Projections

Current Projections is separate from Forecast Lab. It answers: what does this week look like, and if the current run-rate continues, where do the month, quarter, and year end?

Projection	Method	Use it for
Week	Current Monday-Sunday scheduled booking window.	Short-term cash and staffing pulse without first-of-month zeros.
Month	Month-to-date activity extrapolated through month end.	Monthly run-rate and reserve expectations.
Quarter	Quarter-to-date activity extrapolated through quarter end.	Payroll tax, owner payout, and operating review.
EOY	Year-to-date activity extrapolated through December 31.	Annual revenue, tax reserve, and year-end packet planning.

Forecast Lab Modeling

Forecasting is intentionally split from the main Books view. Current Status shows the business today. Cash Flow separates Scheduled, Settled, and Variance operating views and includes Regional Manager distribution tracking by name/region without treating region expenses as manager-personal costs. Forecast Lab asks what could happen if growth assumptions change.

Driver	Why it matters	Model treatment
Current monthly bookings	Baseline operating volume.	Starting demand before growth levers.
Average booking value	Revenue quality and package mix.	Bookings × AOV × price/mix lift.
Ad spend and target CAC	Paid growth engine.	Paid bookings = ad spend ÷ target cost per booking.
Organic growth	SEO, referrals, repeat customers, brand lift.	Compounded monthly demand growth.
New regions	Territory expansion.	Six-month ramp to steady-state bookings per region.
New performers / hires	Capacity constraint.	Demand above performer capacity is constrained until hiring catches up.
Variable cost ratio	Labor, supplies, travel, processing fees.	Direct cost as a percentage of revenue.
Tax reserve and distribution share	Cash discipline.	Tax reserve is set aside before owner payout pool.

demand = organic demand + paid demand + new-region ramp
capacity = current capacity + new hires * bookings per hire * onboarding ramp
bookings = min(demand, capacity)
revenue = bookings * average booking value * price/mix lift
EBITDA = revenue - operating cost
free cash = EBITDA - tax reserve

Forecast Lab supports named saved scenarios. Saved forecasts and Books operating settings now sync through /api/books/settings when the backend is reachable, with browser-local fallback for Dev resilience. Books cards also expose click-to-open popouts with detailed explanations for KPI, tax, compliance, projection, forecast, and settings boxes.

Compliance Countdown

The Books tab shows reminder countdowns for the next major finance submissions. Payroll tax countdowns now connect to filing packet records that preserve source runs, CPA/admin approval, submission attempts, and stored confirmation or rejection details.

Countdown	Purpose	Source of truth later
IRS Form 941	Quarterly federal payroll tax return.	Paid W-2 payroll runs, packet approval, portal/API submission attempt, confirmation/rejection.
TWC Wage Report	Texas quarterly unemployment wage/tax reporting.	Paid W-2 wage rows, TWC packet approval, portal/API submission attempt, confirmation/rejection.
Texas Franchise	Annual franchise tax and public information report reminder.	Year-end books, entity data, Webfile/CPA confirmation.
W-2 / 1099 Packets	Annual employee and contractor recipient/filer packets.	Payroll/contractor records and provider filing confirmation.

Target Architecture

Admin shell
  → Books tab
    → isolated Books module/app
      → /api/books/* finance API
        → finance_* tenant-scoped tables
        → encrypted bank-feed credentials
        → object/file storage for receipts, tax packets, statements, exports

Existing Postgres is OK: Use the current Optimus Ops database, but add dedicated tenant-scoped finance_* tables.
Do not use JSON notes: Do not store ledger records in BusinessProfile.notes, tenant_config_items, bookings.notes, or ad hoc JSON blobs.
Do not load finance data globally: Books data loads only when the Books tab opens.
Do not store large files in Postgres: Receipts, bank statements, tax packets, and export files belong in file/object storage with metadata in finance tables.

Possible Performance Improvements

June 2026 Dev inspection did not point to slow raw Postgres responses as the main cause of perceived Books/Admin tab delay. Current Dev table sizes are small, common Postgres query plans were sub-millisecond, and backend/database CPU and memory were low during inspection. The more likely contributors are first-click lazy module load, uncompressed static assets, many parallel Books API calls, repeated auth/tenant scope checks, connection-pool fanout, and client-side render work.

Improvement	Why it helps	Status
Preload heavy modules on idle	Keep Books out of the initial Admin shell path, but fetch the Books module after login or during browser idle time so the first Books click does less work.	Candidate
Defer non-default Books data	Load only the default Books view first. Payroll, tax, regional statements, distribution elections, and other deep workpapers can load when their Books subview opens.	Candidate
Enable gzip for Admin static assets	The Admin shell and Books module were served without compression in Dev. Compression should reduce transfer size for large HTML/JS assets.	Candidate
Add Books bootstrap API	Replace the initial fanout of separate schema, accounts, settings, mailbox, worker-secret, Chase, report, expense, and payroll calls with a smaller first-pass payload and fewer repeated auth/context checks.	Candidate
Add request and browser timing	Measure module load, API time, DB time, serialization time, and render time before deeper tuning. This should separate network, backend, Postgres, and browser causes.	Recommended first instrumented step
Tune DB pool only if measured	Default SQLAlchemy pool settings may queue bursts of parallel Books requests, but Postgres itself looked fast. Adjust pool size/overflow only if timings show pool wait or request queuing.	Conditional

Core Finance Tables

Group	Tables	Purpose
Ledger	`finance_accounts`, `finance_journal_entries`, `finance_journal_lines`, `finance_periods`	Double-entry accounting core and period close.
Bank/receipts	`finance_expense_receipts`, `finance_expense_files`, `finance_bank_connections`, `finance_bank_accounts`, `finance_bank_transactions`, `finance_reconciliation_matches`, `finance_documents`	Expense inbox review, private receipt storage metadata, feed import, matching, statements.
Payroll/tax	`finance_payroll_runs`, `finance_payroll_tax_liabilities`, `finance_tax_reserves`, `finance_tax_filing_periods`, `finance_tax_filing_submissions`, `finance_tax_workpapers`	Payroll liabilities, tax reserves, filing packets, submission attempts, confirmations, and future workpapers.
Owners	`finance_owner_distributions`, `finance_owner_equity_accounts`, `finance_shareholder_basis`, `finance_k1_packets`	Owner payouts, equity, basis, K-1 packets.
Exports/audit	`finance_export_jobs`, `finance_export_files`, `finance_audit_events`	Async exports, reports, audit trail.

Every finance row should include tenant_id, timestamps, actor metadata where applicable, status, source, and external IDs where applicable.

Double-Entry Ledger Rules

The backend should post every money event as a balanced journal entry:

sum(debits) = sum(credits)

Assets = Liabilities + Equity

Plain-English event	Ledger treatment
Customer pays deposit before event	Debit Square Clearing; credit Customer Deposits Liability.
Square deposits cash after fee	Debit Bank; debit Processing Fees; credit Square Clearing.
Event is completed	Debit Customer Deposits Liability; credit Event Revenue.
Performer is paid	Debit Performer Labor Expense; credit Bank.
Owner takes distribution	Debit Owner Distribution equity account; credit Bank. Not a business expense.
Payroll tax is due/paid	Credit Payroll Tax Payable when incurred; debit it when paid.

IRS Reporting Specifics

Output	Books data needed	Notes
Form 1120-S	Revenue, deductions, payroll, balance sheet support, shareholder data.	S-Corp annual income tax return workpaper packet.
Schedule K-1 (1120-S)	Owner share, distributions, basis, separately stated items.	Final owner K-1 PDF plus TurboTax entry worksheet.
Form 941	Quarterly wages, federal withholding, employee/employer Social Security and Medicare, deposits.	Employer quarterly federal payroll tax workpaper.
Form 940	FUTA taxable wages, state unemployment tax paid, FUTA deposits.	Annual federal unemployment tax workpaper.
W-2 / W-3	Employee annual wages, withholding, Social Security, Medicare, benefits where applicable.	Annual employee wage packet.
1099-NEC / 1096	Contractor payments, W-9 status, threshold review, excluded reimbursements review.	Contractor information return packet.

Current Dev builds filing-ready payroll tax packets, auto-refreshes W-2-related drafts after W-2 paid confirmation, lets Admin delete drafts before review, and records official portal confirmation after CPA/admin approval. Direct IRS/EFTPS/TWC API transport remains disabled until provider credentials, enrollment, schemas, validation, and confirmation capture are configured.

Texas Reporting Specifics

Output	Books data needed	Notes
Texas Franchise Tax	Total revenue, margin method inputs, compensation deduction inputs, no-tax-due threshold review, entity/officer ownership data.	Annual report generally due May 15, next business day when applicable.
Public Information Report	Officer/director/owner info, entity identifiers, address.	Should be prepared with franchise packet.
Texas Sales/Use Tax	Taxable vs non-taxable revenue, event location/jurisdiction, state/local tax collected.	Applicability must be confirmed by CPA/state guidance for POPN services.
TWC Unemployment	Wages by employee, taxable wage base, tax rate, quarterly wage reports, payments.	Quarterly reports and taxes are generally due by the last day of the month after quarter end.

Owner Distributions, K-1, and TurboTax

Owner distributions are not expenses. They reduce equity/cash and must be tracked separately from payroll and reimbursements.
Distributable cash must be guarded. Tax reserve, payroll reserve, future-event obligations, refund reserve, debt/liabilities, and operating cushion are deducted before a suggested payout pool.
K-1 packets: Final K-1 PDF, box-by-box K-1 values, TurboTax owner entry worksheet, distribution statement, W-2 wage summary for owner-employees, basis worksheet, and CPA notes.
TurboTax direction: Do not promise a direct TurboTax API/import. Produce TurboTax-friendly owner worksheets matching the final K-1 boxes so owners can enter values cleanly into personal TurboTax.

Complete Remaining Build List

Books now tracks the payroll foundation as a living checklist. Core payroll review, payment closeout, and direct payroll tax filing packet controls are complete in Dev; later items still require automated money movement, ledger posting, provider tax API transport, and attachment storage.

Status	Area	Still needed / shipped boundary
Done in Dev	1. Admin request dashboard	Books Payroll can list, create, copy, and revoke short-lived Team W-4/W-9 request links. Request URLs are only displayed at creation because tokens are stored hashed.
Done in Dev	2. W-9 verification gate	Contractor payroll review lines are blocked unless the contractor W-9 status is verified. Invalid/unverified contractors are not payable in contractor review generation.
Done in Dev	3. Payroll run tables	Approved review batches can create draft payroll run tables. These are prep tables only: no money movement, no provider submission, no tax filing, and no ledger posting yet.
Done in Dev	4. W-2 tax calculation preview	Payroll runs can calculate W-2 preview fields for federal withholding, employee/employer FICA, FUTA/SUTA estimates, net pay, and Team pay-stub preview lines. This does not submit payroll, create tax deposits, post ledger entries, file forms, or move money.
Done in Dev	4A. W-2 external payroll closeout	Calculated W-2 payroll runs can be approved, prepared as CSV export files for an outside payroll provider, downloaded, and externally confirmed paid. Confirmation locks pay-stub metadata, records payroll-tax liability notes, and refreshes draft IRS 941/EFTPS/TWC/940/W-2 packets. Books does not submit payroll, make tax deposits, post ledger entries, file forms, or move money.
Done in Dev	4B. Payroll review line controls	Payroll review lines can be held, excluded, adjusted, and restored with required reasons before approval. Held/excluded/problem lines remain visible for audit but are excluded from payable review totals and payroll run creation.
Done in Dev	5. Contractor payment prep	Calculated contractor runs can create contractor payment batches with W-9 gating, annual 1099 threshold tracking, Admin review/approval, and Team statement packet previews. This does not export payments, confirm provider payments, file 1099-NEC/1096 forms, post ledger entries, or move money.
Done in Dev	6. Contractor export and 1099 workpapers	Approved contractor batches can prepare a CSV/check-register export, record external payment confirmation, split reportable 1099 compensation from reimbursement exclusions, and show 1099 workpapers. This does not transmit provider payments, file 1099-NEC/1096 forms, post ledger entries, or move money.
Done in Dev	6A. Direct payroll tax filing packets	Books can generate IRS 941, EFTPS deposit, TWC wage report, IRS 940, W-2/W-3, and 1099-NEC/1096 packets from paid payroll/payment records, auto-refresh W-2-related draft packets after W-2 payment confirmation, delete draft packets before review, submit them for CPA/admin review, approve them, download packet CSVs, and record direct portal/API submission attempts with submitted/accepted/rejected or blocked-missing-provider status.
Next	Contractor filing and ledger posting	Provider integration for actual 1099-NEC/1096 transport, payment reconciliation, government receipt attachment storage, and ledger posting.
Next	Ledger core	Replace modeled KPIs with ledger summaries; period close/lock; universal reversal UX; journal attachments; recurring journals; ledger backup/export; data-quality checks.
Partial in Dev	Revenue and Square	Successful Square webhook confirmations now post booking deposits/final payments and tips into Square Clearing, Customer Deposits, and Tips with idempotent journal entries. Still needed: Square refund/fee/dispute/payout/location activity pulls; matching fees, refunds, transfer dates, Square account/location, and net Chase deposits through Square Clearing; AR for unpaid invoices; refund exposure; and event-earned revenue recognition rules.
Next	Expense inbox	Advanced filters/export; duplicate detection; batch approve/post; vendor memory; recurring expense rules; Team expense submission; OCR/search fallback for low-confidence files.
Next	Bank feeds and Chase batches	Choose Chase-compatible provider; encrypted credentials; mapped Chase accounts/last4/start date; transaction import jobs; statement fallback; reconciliation queue for Square deposits, payroll withdrawals, contractor payments, tax payments, transfers, owner distributions, expenses, and refunds; manual match/split/ignore/create-entry workflows. Any full Chase payment rail must use draft batches, line review/edit/hold, authorized human approval, final submit confirmation, provider response capture, cancel/void handling, and reconciliation back to imported activity.
Done in Dev	7. Regional distribution elections	Regional Manager review lines with distribution capacity can be saved as draft elections, split between distribution and expense support reserve, submitted, and approved as workpapers. This does not post ledger entries or move money.
Next	Regional waterfall	Ledger-derived realized proceeds tiers; manager W-2 wage postings; ledger posting for approved distribution/equity movement; shared-region equal split; optional future split weights; all-up owner pool report; proceeds-cap enforcement.
Next	Owner equity	Owner equity accounts; capital contributions; distributions; shareholder basis tracking; owner distribution approval workflow; owner packet export.
Next	Payroll tax production smoke	After explicit production approval: deploy the Admin/backend slice, verify new tax tables and protected routes, generate a real-period packet from paid payroll data, CPA-review/approve it, file through the official portal, and record the confirmation or rejection in Books.
Next	Annual/correction tax packets	Form 941-X and TWC correction packets, 1120-S, K-1, Texas franchise/public information, sales/use if applicable, government receipt uploads, and final PDF packet storage.
Next	Provider tax API transport	IRS/TWC/EFTPS API transport adapters, encrypted provider credentials, enrollment validation, request schema validation, transmission audit events, rejection handling, and provider confirmation capture.
Next	Reports and exports	Full report endpoints; filters by date/account/region/service/performer/vendor/status/source; CSV/XLSX/PDF/JSON exports; CPA packet; monthly/quarterly snapshots.
Next	Security and audit	Finance scopes in UI; approval scopes; immutable audit events; sensitive-field redaction; packet download audit; step-up reauth for high-risk actions.
Future	Admin Optimus key rotation automation	After Books payroll is production-ready, build the full Key Rotation run engine in Admin Optimus: persisted rotation runs, generated/staged keys, per-target validation, promote/retire/rollback, and the N8N inbound Header Auth duplicate-webhook or gateway strategy. The current Key Rotation tab remains manual/MVP status only.
Next	Automation and testing	Bank sync jobs; Graph renewal monitoring; report snapshot refresh; failed job alerting; webhook/import replay tools; backend tests and UI smoke tests.

The detailed source list lives in BOOKS-Finance-Operations.md under Complete Remaining Build List.

Phased Rollout

Phase	Scope	Safety rule
1	Read-only Books dashboard from Scheduling data.	No writes, no bank feeds, no money movement.
2	Finance backend skeleton, chart of accounts, double-entry ledger.	Tenant-scoped tables and finance RBAC first.
3	Bank feeds, receipt inbox, reconciliation queue.	Read-only feed import before transfers.
4	Payroll, contractors, owner equity/distributions.	Approval and audit required for distributions.
5	IRS/Texas/K-1/TurboTax workpaper packets.	CPA/owner review before any submission.
6	Controlled filing/payment automation.	Only after validated ledger periods and explicit approval controls.

🔗 External Services & Dashboards

Core Integrations

Service	Purpose	Dashboard / Docs
📱 Vonage	SMS messaging + Voice (phone number: +1 972-777-6725)	dashboard.nexmo.com · Docs
🗣️ OpenAI GPT Realtime	Active Bella voice stack — single speech-to-speech model through FastAPI bridge	Realtime docs
⚡ xAI Grok Realtime	Alternate realtime bridge only when selected in Voice Agent settings	console.x.ai
🗄️ Cartesia (legacy)	Archived former Bella STT/TTS stack. Not deployed and not in the current call path.	Legacy docs
💳 Square	Hosted checkout links + Tap-to-Pay — deposit + final balance	Square Dashboard · API Docs
🔄 N8N	Workflow automation (self-hosted)	n8n.optimus.systems · Docs
📅 Google Calendar	Per-performer scheduling & availability	calendar.google.com · API Docs
🔐 Google OAuth	Admin portal authentication	GCP Console · Docs

Infrastructure

Service	Purpose	URL / Notes
🌐 Website	Public-facing site	PoppinPartiez.com
🛡️ Admin Portal	This portal	admin.poppinpartiez.com
⚙️ Backend API	FastAPI backend via admin domain	admin.poppinpartiez.com/api
🐳 VPS / Docker	Nginx + Traefik hosting	212.38.95.250 · Docker containers
📊 Google Search Console	SEO monitoring & indexing	search.google.com/search-console
📈 Google Analytics	Website traffic analytics	analytics.google.com
📢 Google Ads	Paid advertising campaigns	ads.google.com

📱 Admin Portal Guide

Getting Started

Sign in with an authorized Microsoft or Google account (set in Users & Access)
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
🧰 Manual Actions	Prepare/log/send manual payment requests, invoices, receipts, corporate files, and schedule overrides with preview and audit reason
💬 SMS Templates	Customize automated messages — use {{variables}} for dynamic content
🔗 Integrations	Vonage, Square payment accounts, N8N webhook URLs
👤 Users & Access	Manage authorized admin accounts, roles, and SSO client IDs
� Dispatch	Scoring weights for performer auto-assignment algorithm
📞 Phone Routing	Routing mode (Off/Normal/Bypass/Debug), on-call, ring priorities, and Bella message-taking recovery
🔔 Notifications	Per-region notification recipients and notification type toggles
💬 Messages	Two-way SMS inbox — view and reply to all customer texts, manage opt-outs
📚 Docs	This documentation section, including BookingWorkflow, manual workflows, and AI placeholder workflow rules

Scheduling Save Discipline

Use normal field edits for draft cleanup and operational notes.
Use finalization/change review for workflow-triggering changes: assignment, price, travel, payment type, reschedule, cancellation, and customer/artist notices.
Use Manual Actions when a human needs to send a specific payment request, invoice, receipt, corp document, or schedule override outside the automated flow.
Use AI recommendations as structured proposals until FastAPI validates and records the final action.

💬 Messages & SMS Compliance

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.

Keyword (any of)	Action
`STOP, END, QUIT, CANCEL, UNSUBSCRIBE, REVOKE, OPT OUT, STOPALL, OPTOUT`	Customer is opted out — auto-confirmation sent — all future sends blocked server-side
`START, UNSTOP, YES, RESUBSCRIBE, OPTIN`	Customer is re-subscribed — confirmation sent
`HELP, INFO`	Auto-reply with business name, phone, and STOP info

Disclosure Footer

The first SMS in any new conversation should include: "Reply STOP to opt out, HELP for help. Msg & data rates may apply." Customers may also opt out with END, QUIT, CANCEL, UNSUBSCRIBE, REVOKE, OPT OUT, or clear everyday-language requests such as "please opt me out."

Using the Messages Tab

Conversations are listed in the left panel, sorted by most recent activity
Filters: All · Unread · Active · Opted Out
Search by customer name, phone, message text, or booking reference
Click a conversation to view the full thread
Type a reply at the bottom (Cmd/Ctrl+Enter to send)
Opted-out conversations are greyed out and the reply box is disabled — server enforces this regardless of UI state
Manual opt-out: click "🚫 Opt Out" in the thread header (e.g. customer requested verbally)
Voice opt-out: texts like "stop calling me" create a voice opt-out record, and outbound Place Call dialing is blocked for voice-opted-out numbers
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

⚙️ Config Reference

FastAPI Backend Endpoints

Endpoint	Method	Auth	Description
`/api/popn/auth-info/{slug}`	GET	None	Google Client ID + allowed emails (for login)
`/api/popn/admin/config/{slug}`	GET	Google OAuth	Full config for admin portal
`/api/popn/admin/config/{slug}`	POST	Google OAuth	Save config → PostgreSQL
`/api/popn/config/{slug}`	GET	X-Internal-Key	Full config for N8N workflows
`/api/popn/routing/{slug}/config`	GET	X-Internal-Key	Phone routing mode + performer phones
`/api/popn/transfer/{slug}/initiate`	POST	X-Internal-Key	Initiate direct or supervised Vonage transfer
`/api/popn/transfer/{slug}/answer`	GET	HMAC-signed URL	NCCO answer URL for direct named transfer fallback
`/api/popn/transfer/{slug}/screen`	GET	HMAC-signed URL	Staff press-1 accept prompt for supervised routing
`/api/popn/transfer/{slug}/join`	GET	HMAC-signed URL	Moves accepted staff and caller into the same conversation
`/api/popn/notifications/{slug}`	GET/PUT	X-Internal-Key	Notification recipient CRUD
`/api/popn/sms/inbound/{slug}`	POST	None (Vonage)	Vonage inbound SMS webhook + STOP/HELP handler
`/api/popn/sms/log/{slug}`	POST	X-Internal-Key	N8N logs sent SMS to conversation history
`/api/popn/sms/optout-check/{slug}?phone=...`	GET	X-Internal-Key	N8N pre-send opt-out check
`/api/popn/admin/sms/conversations/{slug}`	GET	Google OAuth	List conversations (admin Messages tab)
`/api/popn/admin/sms/conversations/{slug}/{id}/send`	POST	Google OAuth	Admin manual reply (opt-out enforced server-side)
`/api/popn/admin/sms/optouts/{slug}`	GET/POST	Google OAuth	List/add SMS or voice opt-outs by channel
`/api/popn/admin/sms/optouts/{slug}/{phone}?channel=sms`	DELETE	Google OAuth	Re-enable SMS or voice channel (with documented consent)

🎉 Poppin' Partiez

🏢 Business Information

📋 Business Details

📍 Service Area & Travel

💳 Payment Settings

🎨 Performers / Contractors

📍 Live Team Locations

💰 Service Pricing

🎨 Average Guests Per Artist Hour

🎨 Individual Services

⭐ Value Packages

📅 Scheduling

⏰ Booking Rules

🗺️ Service Regions

Send Booking Details

💬 SMS / Message Templates

🔗 Integrations

📱 Vonage (Phone & SMS)

📧 Microsoft Graph (Outlook) — used by admin Send actions to email from inquiry@poppinpartiez.com. Encrypted at rest. Default setup uses Azure app permissions and does not need a refresh token.

💳 Payment Accounts — define every Square account this business can issue payment links from. Each region (in Notifications) picks one of these by name. Square handles all payment collection (incl. tipping) on its hosted page so you stay out of card data.

🏦 Chase / J.P. Morgan Banking — encrypted credential setup for readiness checks and future approval-gated bank-feed work. No bank import, ledger posting, payments, or money movement is enabled from this card.

👤 Users & Access

Authorized Users Owner controls access. Operations Manager is all-region non-owner; Regional Manager is selected-region; Performer is linked-profile.

🚗 Artist Dispatch & Scoring

⚖️ Scoring Weights

📍 Distance & Travel

🎈 Event Type Multipliers

🔔 Regional Notification Routing

📞 Phone Routing

🔀 Routing Mode

⭐ On Call

⚙️ Transfer Settings

🎨 AI Regional Routing Priorities

☎ Place Call

Call Session

Add to Call

Allow Microphone

💬 Messages

📝 Form Submissions

📞 Call Transcripts

🧰 Manual Actions

Hermes — AI Platform Manager

📥 Greenlight Gate Inbox

Coming soon

🎙️ Voice Agent — Stack & Flow

🔀 Active Stack

Vonage / Cartesia / Groq

Vonage / ElevenLabs / Groq

Vonage / xAI Grok Realtime

Vonage / OpenAI GPT Realtime

🔁 Audio Pipeline (per call)

🧭 Conversation Flow — adapts to active stack & enabled capabilities

🔊 ElevenLabs Configuration

✨ OpenAI GPT Realtime Configuration

⚡ xAI Grok Realtime Configuration

🎙️ Customer Test Voice

🧠 Customer Test Brain

📝 Customer System Prompt

🧪 Customer Test Scenarios

🎚️ API Toggles

🗣️ Pronunciation Library — injected into OpenAI/Grok realtime instructions

📚 Knowledge Base — context snippets injected into Bella's system prompt

🛠️ Tool Registry

📚 Poppin' Partiez — System Docs

About This System

📊 Books & Finance Operations

💵 Systems Expenses Breakdown

Fixed Monthly Costs

Usage-Based Costs (per booking funnel)

Direct OpenAI GPT Realtime Rate Card

OpenAI Transcription Add-On

All-In System Cost (estimate)

💳 Payment Processing Fees (separate — cost of doing business)

Combined: System + Processing

Revenue vs Cost (offset analysis)

🏗️ System Architecture

Data Flow

Tech Stack

🗺️ Architecture Diagrams

System Overview

📧 Microsoft Graph (Outlook) — used by admin Send actions to email from `inquiry@poppinpartiez.com`. Encrypted at rest. Default setup uses Azure app permissions and does not need a refresh token.