Files · Predictive Reservation Cancellation Backfill for Small Hospitality Groups

# Predictive Reservation Cancellation Backfill for Small Hospitality Groups
 
> Fill no-shows automatically with AI-driven waitlist activation.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Architecture
 
The system uses a voice-enabled cancellation pipeline (STT → MCP → TTS) orchestrated via `@reaatech/voice-agent-core`. Twilio telephony integration is handled by `@reaatech/voice-agent-telephony`. LLM predictions use the Vercel AI SDK with OpenAI, and responses are cached via `@reaatech/llm-cache`. MCP tools are registered through `@reaatech/mcp-server-tools`, typed schemas come from `@reaatech/agent-mesh`, and typed error handling from `@reaatech/agent-handoff`. Data persistence uses `@vercel/postgres` and observability is provided by Langfuse. A Hono server handles Twilio webhooks and WebSocket media streams.
 
Key flow: A cancellation triggers the backfill system — the reservation is marked cancelled, matching waitlist entries are found, an LLM generates an SMS invitation, and the waitlisted guest is contacted automatically.
 
## Prerequisites
 
- OpenAI API key
- Twilio account (Account SID, Auth Token, phone number)
- Vercel Postgres database
- Langfuse account (optional, for observability)
 
## Environment Variables
 
| Variable | Description | Required |
|---|---|---|
| `OPENAI_API_KEY` | OpenAI API key | Yes |
| `TWILIO_ACCOUNT_SID` | Twilio Account SID | Yes |
| `TWILIO_AUTH_TOKEN` | Twilio Auth Token | Yes |
| `TWILIO_PHONE_NUMBER` | Twilio phone number for SMS | No |
| `POSTGRES_URL` | Vercel Postgres connection string | Yes |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | No |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key | No |
| `LANGFUSE_BASE_URL` | Langfuse base URL | No |
| `PREDICTION_MODEL` | OpenAI model for predictions | No (default: `gpt-5.2-mini`) |
| `LLM_CACHE_EMBEDDING_MODEL` | Embedding model for cache | No |
| `LLM_CACHE_SIMILARITY_THRESHOLD` | Cache similarity threshold | No (default: `0.8`) |
| `LLM_CACHE_DEFAULT_TTL` | Cache TTL in seconds | No (default: `3600`) |
 
## API Endpoints
 
| Endpoint | Method | Description |
|---|---|---|
| `/api/reservations` | GET | List reservations for a restaurant |
| `/api/reservations` | PATCH | Update reservation status (cancelled triggers backfill) |
| `/api/reservations` | POST | Create a new reservation |
| `/api/waitlist` | GET | List waitlist entries + backfill status |
| `/api/waitlist` | POST | Add entry to waitlist |
| `/api/predictions` | GET | Get risk predictions (with/without timeSlot) |
| `/api/health` | GET | Health check |
| `/voice` (Hono) | POST | Twilio voice webhook — returns TwiML |
| `/stream` (Hono) | WebSocket | Twilio Media Streams audio |
| `/status` (Hono) | POST | Twilio status callbacks |
 
## Tech Stack
 
| Package | Purpose |
|---|---|
| `@reaatech/voice-agent-core` | Voice pipeline orchestration (STT → MCP → TTS) |
| `@reaatech/voice-agent-telephony` | Twilio telephony integration |
| `@reaatech/llm-cache` | LLM response caching and similarity matching |
| `@reaatech/mcp-server-tools` | MCP tool registry |
| `@reaatech/agent-mesh` | Typed schemas and message validation |
| `@reaatech/agent-handoff` | Typed error handling and retry logic |
| `@vercel/postgres` | Data persistence |
| `ai` / `@ai-sdk/openai` | Vercel AI SDK + OpenAI for LLM predictions |
| `hono` / `@hono/node-server` | HTTP server for Twilio webhooks + WebSocket |
| `twilio` | Twilio SDK for SMS and voice calls |
| `langfuse` | Observability and tracing |
| `next` | Next.js App Router for API routes and UI |
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).