PRD v1.0 — 2026-03-27

FlowStay HQ v2

The staff-facing intelligence and operations dashboard for hotels running FlowStay AI voice agents. Built from scratch — new stack, new architecture, new philosophy.

Status: Draft
Stack: Phoenix LiveView + BEAM
Launch: ELC + Las Casitas
Voice: LiveKit (VAPI removed)
11
AI Agents
~25
Pages / Views
5
Sentiment Layers
P0–P2
Priority Tiers
1Overview

What we're building

FlowStay HQ v2 is a standalone hotel staff portal. Every page is purpose-built for a specific operational domain. The philosophy throughout is transparency as confidence — scores, failure counts, and escalation rates are shown openly because the numbers are good.

The core bet: Hotel staff dashboards have been built for call center managers. HQ v2 is built for hoteliers who want to understand their AI as a revenue-generating sales team, not monitor it as a phone system.
Philosophy
Sales-first framing
AI agents are salespeople. Metrics are a revenue dashboard, not a call center log.
Design
Dense by default
Power-user tool. More info per screen is better. Hierarchy via size, weight, and color.
UX Rule
Absent beats disabled
Features not applicable to a property are removed from the nav — not greyed, not locked.
2Product Context

Naming + users

Product family

  • ›FlowStay HQ — this product (staff dashboard)
  • ›FlowStay Go — guest-facing booking + visual app
  • ›FlowVue — AI visual rendering tech (domains: Rooms, Spa, Golf, Marina…)
  • ›FlowPilot — live call correction (drift detection + mid-call injection)
  • ›FlowIntel — external name for AI Sales Intelligence page

User roles

  • ›Owner — all pages + multi-property rollup
  • ›General Manager — full access
  • ›Revenue Manager — + Revenue, FlowIntel, Reports
  • ›Front Desk Supervisor — ops + escalations + guests
  • ›Front Desk Staff — live monitor + calls + profiles

~25 pages, 6 sidebar sections

Sidebar navigation
Core Operations
Dashboard P0
Live Monitor P0
Call Explorer P0
Revenue Intelligence
Revenue P1
AI Sales Intelligence P1
Agents (11 pages)
Triage P0
Golf · Spa · Marina P1
Upsells · Ticketing · Guest Services P1
Tables · In-Room Dining · Events · Valet P2
Guests
Guest Profiles P1
Campaigns P2
Escalations + Reports
Escalations P1
Reports P2
Settings
Configuration (Active Agents toggle) P0
Knowledge Base Editor P1
Integrations · Staff & Permissions P2
Active Agents Toggle
Absent beats disabled
Settings → Configuration → Active Agents. Disabled agent pages disappear from sidebar entirely. No greyed entries. Triage is required and cannot be toggled off.

Demo use: disable Golf for Olive Collection. Future: driven by hotel's account profile — same data model, different source of truth. Zero frontend rework.
Global Features
Cmd+K command palette
Global search powered by cmdk. Search: guest name → profile, phone → call history, date → filtered explorer, agent name → agent page.
Property Selector
Multi-property from day one
Header: [ELC] [Las Casitas] [All Properties]. "All Properties" rollup shows aggregated data with per-property attribution on every page.
4The 11 AI Agent Pages

Each agent — full page, own tabs, domain KPIs

Standard tab rail: Overview Calls Domain Tab(s) AI Insights FlowDojo

Triage
Valentina / Sofia · Required
Overview Calls Routing Map Extensions FlowDojo
  • Transfer accuracy %
  • Misroute rate
  • Language detection EN/ES
  • 40+ extension accuracy
  • Sankey diagram: full call flow
Golf
Tee times · toggleable
Overview Calls Tee Times Grid AI Insights FlowDojo
  • Bookings + revenue
  • Cart + lesson add-on rates
  • Weekly slot grid (AI/available/gone)
  • Lost bookings (availability)
Spa
Treatments · toggleable
Overview Calls Appointments Treatment Perf. AI Insights FlowDojo
  • Treatment type breakdown
  • Therapist fulfillment %
  • Upsell: standard → upgraded
  • Allergen flags surfaced
Marina
Slips · unique spatial UI
Overview Calls Marina Map ✦ Reservations AI Insights FlowDojo
  • Overhead dock map (spatial)
  • FlowVue engagement rate
  • Boat size distribution
  • Fuel dock add-on rate
Upsells
Cabanas, massage, etc.
Overview Calls Product Perf. Upsell Funnel AI Insights FlowDojo
  • Acceptance rate %
  • Revenue attributed
  • Funnel: offer → pitch → close
  • FlowPilot-assisted recoveries
Guest Services
Action tickets (towels, maintenance…)
Overview Calls Request Queue Room Health AI Insights FlowDojo
  • Live Kanban: New→Resolved
  • Room health grid (recurring issues)
  • Avg response + resolution time
  • Repeat request rate
In-Room Dining
Orders · real-time kitchen view
Overview Calls Order Queue ✦ Menu Perf. AI Insights FlowDojo
  • Live Kanban (kitchen uses this)
  • Avg order value + items
  • Peak order time heatmap
  • Top 5 menu items
Events
Venue bookings · pipeline stages
Overview Calls Events Calendar Venue Availability AI Insights FlowDojo
  • Pipeline: Inquiry→Confirmed
  • Calendar color-coded by type
  • Venue grid × days availability
  • Stalled pipeline detection
+ 3 more
Ticketing · Table Reservations · Valet
All have Calls tab AI Insights FlowDojo
  • Ticketing → Whistle sync health
  • Tables → Special Requests action list
  • Valet → live queue for valet stand
5Guest Intelligence

The "Know Before They Arrive" system

Hero Feature
"Know Before They Arrive" strip
AI-generated 3-4 sentence briefing at the top of every guest profile when an active/upcoming booking exists. Includes staff-facing suggested opening line. The single highest-value element on the page.

"Maria Rodriguez arrives June 12. Anniversary trip, 4th visit. Last stay she mentioned wanting to try the spa but didn't book it. Owns a 38ft sailboat. Suggested opening: offer Couples Spa package and ask about docking."
Unique feature
"Preview as Guest" button
Opens FlowStay Go in staff-side preview mode with the guest's profile pre-loaded. AI knows it's them. Staff experiences exactly what the guest would experience. Verify context before important arrivals. Use for front desk training.
Guest signals
3-tier memory + editable signals
Preferences, interests, and inferred signals all shown with edit buttons — staff can correct AI inferences inline. Each signal has a Lucide icon (no emojis). Examples: Celebrates anniversary in June · Sailboat owner (38ft, deep-water slip) · Spend tier: Premium · Golfer · Travels with kids.
Review Risk Flag
Departures to Watch
When closing sentiment on final call of stay is negative AND departure is within 24h: yellow warning banner on guest profile + "Departures to Watch" widget on Dashboard. Optional: trigger proactive Campaigns outreach before checkout.

Recovering a review risk before checkout is worth more than any upsell.
6Call Detail Modal

The complete story of a single call

Shared component — triggered from Call Explorer, Live Monitor, Guest Profile, AI Sales Intelligence.

Stereo Waveform — WaveSurfer.js
AGENT ▇▅▃▂▄▆▄▂▃▅▇▅▃ ↑
──────────────● ⚠️ ✦ ────────────── ← center divider + playhead
GUEST ▇▅▃▂▄▆▄▂▃▅▇▅▃ ↓
Agent channel grows UP (purple). Guest channel grows DOWN (orange). FlowPilot markers on center divider: ⚠️ amber = drift, ✦ blue = engaged. Powered by WaveSurfer.js with splitChannels: true.
Tab: Transcript
Full interleaved stream: agent utterances, guest utterances, tool call events (monospace: tool name + params + ✅/❌), FlowPilot events, transfers. Every line clickable: "Jump to audio" or "Jump to visual" (opens FlowVue panel at that timestamp).
Tab: Quality
15 dimensions with progress bars. Greeting, Intent Detection, Triage, Natural Language, Bilingual, Knowledge Base, Tool Correctness, Error Recovery, Policy Compliance, Closing, White Glove Language, Upsell, Personalization, Confirmation Accuracy, Emotional Intelligence.
FlowVue Side Panel
Slides from right edge. Renders FlowStay Go widget synced to audio scrubber. Scrub to 0:42 → widget shows state at 0:42. Tool events replay at original timestamps. "Guest did not open FlowVue during this call" = signal, not an error.
7Guest Sentiment System

5 layers — not a column, a system

Runs across every call, every guest, every stay. Surfaces proactively when something goes wrong.

1
Per-Utterance — real-time
Every utterance scored as it's transcribed. Dimensions: tone (calm/frustrated/confused/distressed/delighted), intensity (mild/moderate/strong), direction (improving/stable/declining). Feeds Live Monitor sentiment ring. Drop below threshold = FlowPilot drift fires.
2
Per-Call Arc — post-call
Opening, peak positive, peak negative, closing sentiment. Net delta: did they end better or worse than they started? Gradient overlay on waveform timeline — region shifts neutral → amber → red where call degraded.
3
Per-Stay Trajectory — longitudinal
All calls in one stay plotted as a timeline on Guest Profile. Declining trajectory mid-stay = churn risk + review risk. Recovered trajectory = success story. Informs "Know Before They Arrive" for next stay.
4
Real-Time Alerting
Level
Trigger
Where
Watch
Sentiment drops to frustrated
Live Monitor alert strip with link
Escalate
Distressed OR trigger phrase ("I want to speak to a manager")
Notification badge + card border pulses red
Critical
Max negative + FlowPilot failed + call still live
"Take Call" button — staff clicks, AI steps aside
5
Cross-Stay Patterns — AI Insights
"Guests who call about AC issues have 73% chance of declining sentiment on next call." "Check-in calls 3-5 PM have lowest opening sentiment — arriving guests after long travel." "Sentiment dips at 4-minute mark in In-Room Dining calls — shorten the call." Surfaces in AI Insights tab on each agent page.
8AI Sales Intelligence (FlowIntel)

The anti-Q-Concierge page

Shows wins AND losses — because we're confident the ratio is good. No other AI voice provider does this. This is the page that proves FlowStay is different.
Wins Board
FlowPilot saves · Recovery rate · Upsells landed · Revenue from recoveries+upsells. Each with count + % + link to example call.
Failure Transparency
Glitches · Losses by reason (price/availability/timing) · Bad escalations (AI-caused vs appropriate) · FlowPilot failed saves.
Tactics Breakdown
Post-call AI analysis: mirroring, scarcity, social proof, objection handling, anchoring, strategic silence. Which tactics correlated with closes. Trend builds over time.
Objection Library
Every objection + AI response + outcome. Best-performing response highlighted per objection. "47 times this month" frequency badge on high-volume objections.
The "Almost" List
Calls that reached final step and didn't complete. Sorted by booking value. Highest-value leads in the system — flagged for human follow-up.
Weekly Coaching Summary
AI-generated paragraph, refreshed every Monday. "This week your AI closed 23% better than last week. The biggest driver was improved objection handling on price…" The reason a GM opens this page every Monday morning.
9Frontend Tech Stack

Locked choices, no emojis

Waveform
WaveSurfer.js
Stereo dual-channel, marker plugin for FlowPilot events, pre-computed peaks, ~40KB
Command Palette
cmdk
Cmd+K global search — same as Linear
Charts
Visx (D3)
Custom shapes: heatmaps, funnels, Sankey diagrams
Components
shadcn/ui
Headless, accessible, dense data tables + popovers
Animations
Framer Motion
Intent tag pop-ins, panel slides, sentiment easing
PDF Export
@react-pdf/renderer
Print-quality reports for ownership groups + boards
Icons
Lucide Icons
Stroke-based, currentColor, 1.5px / 20px. No emojis anywhere. Phosphor as overflow.
Theme
CSS custom props
Dark + light, both first-class. User-selectable. One token set per theme.
10BEAM Architecture Advantages

Why this stack enables things competitors can't replicate

Not "faster" — architecturally different. Most hotel software is Rails or Django with 30-second polling. "Multi-tenancy" means filter by hotel_id. FlowStay HQ on BEAM is a different category of system.
Eternal Guest Session
GenServer per guest, lives the entire stay. Every call, request, and interaction accumulates. When Maria calls at 9 AM, the AI has full context from her 7 AM wake-up call — no DB query.
Node/Python: Redis + complex session reconstruction required
Property-Level Failure Isolation
ELC on its own supervision tree. Las Casitas on its own. Bug in ELC crashes and restarts ELC's supervisor only. Las Casitas never blinked.
Node: crash = restart everything
Hot Code Reload as Product Feature
Push a new system prompt or FlowPilot logic to all active call processes simultaneously — while calls are in progress. Zero dropped calls. Zero downtime.
Node: restarts server. Python: restarts workers.
ETS Zero-Latency Guest Index
DB read ~5ms. Redis ~1ms. ETS ~1 microsecond. Room phone call: guest profile loads before first ring ends. AI never touches Postgres for a guest lookup during a live call.
Every other stack: database or cache round-trip on every call
LiveView Presence
Track every connected staff client at socket level. "GM Sarah + Front Desk Miguel are watching this call." Foundation for supervisor whisper. No external WebRTC needed.
Socket.io / ActionCable: external coordination layer required
PubSub Fan-Out
Call ends + booking confirmed → one broadcast. Simultaneously: Live Monitor removes card, Dashboard KPI ticks, Call Explorer prepends row, Agent page updates rate, Guest Profile adds booking. No polling, no stale data.
REST APIs: polling or separate WebSocket coordination
11Priority Tiers

What ships when

P0

Before first hotel demo

Everything a GM needs to be impressed in a live demo walkthrough.

◆
Dashboard + Live Monitor + Call Explorer
First impressions — the pages a GM sees before anything else
◆
Call Detail Modal with stereo waveform
Dual-channel WaveSurfer waveform is the visual differentiator in demos
◆
Triage agent page
Every single call flows through Triage — must be demo-ready
◆
Sentiment alerting (Watch / Escalate / Critical)
Safety net that shows we take quality seriously
◆
Active Agents toggle in Settings
Required — disable Golf for Olive Collection demo
◆
Multi-property (ELC + Las Casitas)
Both properties are in scope at launch
P1

Before GA launch

Full product surface — everything hotels need for day-to-day operations.

◆
AI Sales Intelligence (FlowIntel)
The page that proves differentiation from competitors
◆
All 11 agent pages with domain tabs + AI Insights
Core operational value for hotel staff
◆
Guest Profiles (full — signals, trajectory, Preview as Guest)
"Know Before They Arrive" is a differentiated WOW moment
◆
Review Risk flag + Departures to Watch
High-value retention feature, only possible with full call intelligence
◆
Knowledge Base Editor
Staff-accessible KB fixes are highest-leverage quality action
P2

Post-GA roadmap

Campaigns, Reports, supervisor whisper, full RBAC, social enrichment, FlowVue domain expansion.

12Open Engineering Questions

7 blockers that need answers

1
Does call record store visual_session_id when SMS link is sent? Required for FlowVue panel sync in call replay.
Blocks: FlowVue panel
2
What is the sentiment scoring implementation — utterance-level in Elixir pipeline, or post-call via LLM judge? Determines if Layer 1 real-time alerting is achievable.
Blocks: Sentiment L1
3
How is per-call audio stored and served? S3 presigned URLs? Direct from LiveKit recording?
Blocks: Waveform player
4
Does Boppy recording deliver true stereo (agent L, guest R)? Confirmed in design session but needs engineering verification.
Blocks: Dual-channel waveform
5
Is ETS maintained per-property or globally? Affects multi-property isolation guarantees.
Blocks: Multi-property
6
What is the data model for guest stay detection — how do we know calls 1-4 are all "one stay"? Check-in/checkout timestamps? Room association?
Blocks: Sentiment L3
7
Whistle API documentation needed for Ticketing agent integration — endpoints for ticket creation, status updates, sync confirmation.
Blocks: Ticketing agent
FlowStay HQ v2 · PRD v1.0 · 2026-03-27 Source: memory/flowstay-hq-prd.md