Files · Instant lead response agent for fitness studios

# Instant lead response agent for fitness studios
 
> Auto-reply to inbound lead forms in under 2 seconds, matching chain studio speed. Built with Next.js 16+ App Router, Hono, Vercel AI SDK, and the `@reaatech/*` agent ecosystem.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## What it does
 
A fitness studio receives a lead form submission on their website. This system catches the webhook, classifies the prospect's intent (e.g. "trial class booking", "pricing inquiry", "general question"), routes the request to the right agent profile, generates a personalized natural-language reply with pricing and scheduling details, stores the interaction for follow-up, and returns the response — all in under two seconds.
 
## Architecture
 
```
lead form → Hono POST /api/leads → classify intent via agent-mesh-classifier
         → route via agent-mesh-router → generate LLM response (Vercel AI SDK)
         → store to agent-memory → return JSON response
```
 
- **Next.js 16+ App Router** — hosts the Hono API routes via the `hono/vercel` adapter
- **Hono** — lightweight, typed HTTP framework for the API layer
- **Vercel AI SDK** (`ai` + `@ai-sdk/openai`) — provider-agnostic LLM streaming and generation
- **Zod** — request validation and type coercion
- **Langfuse** — observability and tracing for every LLM call
- **`@reaatech/agent-mesh`** — orchestrates the multi-agent pipeline
- **`@reaatech/agent-mesh-router`** — routes classified intents to the correct agent profile
- **`@reaatech/agent-mesh-classifier`** — classifies inbound lead intent
- **`@reaatech/agent-memory`** / **`@reaatech/agent-memory-storage`** — persists lead interactions for continuity
 
## Quick start
 
```bash
pnpm install
cp .env.example .env.local   # then fill in your keys
pnpm dev                     # next dev on http://localhost:3000
```
 
## API reference
 
### `POST /api/leads`
 
Submit a lead form for auto-reply.
 
**Request body** (Zod-validated):
 
| Field              | Type     | Required | Description                          |
|--------------------|----------|----------|--------------------------------------|
| `name`             | string   | yes      | Prospect's full name                 |
| `email`            | string   | yes      | Prospect's email address             |
| `phone`            | string   | no       | Contact phone number                 |
| `preferredClassType` | string | no       | E.g. "yoga", "HIIT", "spin"         |
| `message`          | string   | yes      | Free-text message from the prospect  |
| `studioId`         | string   | yes      | Identifies the fitness studio        |
 
**Response** (200):
 
| Field              | Type     | Description                               |
|--------------------|----------|-------------------------------------------|
| `leadId`           | string   | Unique identifier for the lead            |
| `welcomeMessage`   | string   | Personalized greeting and acknowledgment  |
| `scheduleSummary`  | string   | Relevant class times / next steps         |
| `nextSteps`        | string   | What the prospect should do next          |
| `agentId`          | string   | Which agent profile handled the reply     |
| `responseTimeMs`   | number   | End-to-end processing time in ms          |
 
### `GET /health`
 
Simple health-check endpoint.
 
**Response** (200):
 
```json
{
  "status": "ok",
  "version": "1.0.0",
  "uptimeMs": 123456
}
```
 
## Environment variables
 
| Variable                 | Required | Description                           |
|--------------------------|----------|---------------------------------------|
| `OPENAI_API_KEY`         | yes      | API key for OpenAI LLM access         |
| `LANGFUSE_PUBLIC_KEY`    | yes      | Langfuse project public key           |
| `LANGFUSE_SECRET_KEY`    | yes      | Langfuse project secret key           |
| `LANGFUSE_BASE_URL`      | yes      | Langfuse API base URL                 |
| `LEAD_RESPONSE_MODEL`    | yes      | Model identifier for lead responses   |
| `LEAD_AGENT_ENDPOINT`    | no       | MCP agent endpoint (default: http://localhost:3100) |
| `NEXT_PUBLIC_APP_NAME`   | no       | Display name for the app (UI surface) |
 
## Testing
 
```bash
pnpm test          # vitest run with coverage (60+ tests, 90%+ coverage)
```
 
Unit and integration tests live in `tests/`, mirroring `src/`. The test suite covers request validation, intent classification, agent routing, LLM response generation, and memory storage.
 
## 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).