Files · Automated no-show and late-cancel enforcement for studios

# Automated No-Show and Late-Cancel Enforcement for Studios
 
Chase no-shows and late cancels automatically, reducing revenue leakage.
 
## Overview
 
Studio managers lose revenue when members skip classes or cancel late. This recipe builds a **document-pipeline** system that detects no-shows and late-cancels from attendance records, applies cancellation policy, and sends SMS notifications via Twilio — all without manual effort.
 
Built with **Next.js 16+ (App Router)** and **Fastify**, using 5 REAA packages from the agent-runbook ecosystem.
 
## Architecture
 
The pipeline processes attendance records through these stages:
 
1. **Attendance Analyzer** — Uses `@reaatech/agent-runbook-agent`'s `AnalysisAgent` to classify no-show/late-cancel severity
2. **Policy Enforcer** — Applies configured policy (fee amounts, warning thresholds, suspension rules)
3. **Notification Service** — Sends SMS via Twilio for each actionable result
4. **Runbook Builder** — Generates a structured enforcement runbook using `@reaatech/agent-runbook-runbook`
5. **Alert Generator** — Generates Prometheus alert definitions via `@reaatech/agent-runbook-alerts`
6. **Health Check Generator** — Generates Kubernetes probe YAML via `@reaatech/agent-runbook-health-checks`
 
## REAA Packages Used
 
| Package | Role |
|---------|------|
| `@reaatech/agent-runbook` | Core domain types, Zod schemas, validation, error classes |
| `@reaatech/agent-runbook-agent` | AI agent (`AnalysisAgent`) for LLM-powered analysis |
| `@reaatech/agent-runbook-runbook` | Runbook assembly, formatting, completeness validation |
| `@reaatech/agent-runbook-alerts` | Alert extraction and generation (Prometheus/Datadog/CloudWatch) |
| `@reaatech/agent-runbook-health-checks` | Health check identification and Kubernetes probe generation |
 
## Third-Party Packages
 
- `twilio` — SMS notifications
- `zod` — Runtime schema validation
- `langfuse` — LLM observability and tracing
- `ai` (@vercel/ai-sdk) + `@ai-sdk/openai` — Provider-agnostic LLM message generation
- `fastify` — Secondary HTTP server with enforcement routes
 
## Prerequisites
 
- Node.js >= 22
- pnpm 10
- Twilio account (Account SID, Auth Token, a phone number with SMS capability)
- OpenAI API key
- Langfuse account (for LLM tracing)
 
## Setup
 
```bash
pnpm install
cp .env.example .env
# Fill in your credentials
```
 
## Usage
 
### Next.js Dev Server
 
```bash
pnpm dev
```
 
Enforcement endpoint: `POST http://localhost:3000/api/enforce`
Health: `GET http://localhost:3000/api/health`
 
### Fastify Server
 
```bash
npx tsx src/api/fastify-server.ts
```
 
Runs on port 3001 by default.
- `GET http://localhost:3001/health`
- `POST http://localhost:3001/enforce`
- `GET http://localhost:3001/runbook`
- `GET http://localhost:3001/alerts`
 
### Example Enforcement Request
 
```bash
curl -X POST http://localhost:3000/api/enforce \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "memberId": "m1",
        "classId": "yoga-101",
        "scheduledDate": "2026-06-08T10:00:00Z",
        "status": "no-show"
      },
      {
        "memberId": "m2",
        "classId": "spin-202",
        "scheduledDate": "2026-06-08T14:00:00Z",
        "status": "late-cancel"
      }
    ]
  }'
```
 
## API Reference
 
| Route | Method | Description |
|-------|--------|-------------|
| `/api/health` | GET | Health check (Next.js) |
| `/api/enforce` | POST | Run enforcement pipeline (Next.js) |
| `/health` | GET | Health check (Fastify) |
| `/enforce` | POST | Run enforcement pipeline (Fastify) |
| `/runbook` | GET | Get enforcement runbook markdown (Fastify) |
| `/alerts` | GET | Get alert definitions (Fastify) |
 
## Testing
 
```bash
pnpm test
```
 
Runs vitest with coverage reporting. Target: >= 90% on lines, branches, functions, and statements for runtime code (`src/**/*.ts`, `app/**/route.ts`).
 
## License
 
MIT