Files · Automated family inquiry to instructor match agent for tutoring centers

# Automated Family Inquiry to Instructor Match Agent
 
Instantly match incoming family inquiries to the best instructor without manual triage.
 
## Problem
 
The admissions coordinator at a tutoring center receives dozens of family inquiries daily via web forms, phone, and email. Each inquiry requires manually assessing the student's needs, checking instructor availability, and finding the best fit. This process is slow, error-prone, and often leads to lost leads or mismatched pairings.
 
## Architecture
 
- **Next.js 16+ App Router** — frontend page with inquiry form + API route handlers
- **Fastify** — backend MCP server with agent orchestration endpoints
- **@reaatech/agent-mesh ecosystem** — intent classification (classifier), MCP dispatch (router), Firestore sessions (session), structured observability (observability), MCP server exposure (mcp-server)
- **Zod 4.4** — runtime schema validation
 
### Flow
1. Family submits inquiry via web form (student name, subject, grade level, etc.)
2. Orchestrator parses and classifies the inquiry using `classifierService`
3. Instructor matching service ranks available instructors by fit
4. Router dispatches the inquiry to the best-match instructor via MCP
5. Session management tracks multi-turn conversation state
6. Response returned to the family with matched instructor details
 
## Setup
 
```bash
pnpm install
pnpm dev        # starts Next.js + Fastify
pnpm test       # runs vitest with coverage
pnpm typecheck  # TypeScript type checking
pnpm lint       # ESLint
```
 
## Environment Variables
 
See `.env.example` for all required variables.
 
## API Endpoints
 
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/inquiry` | Submit a family inquiry |
| GET | `/api/session/:sessionId` | Get session status |
| GET | `/api/instructors` | List available instructors |
| GET | `/health` | Health check |
| GET | `/mcp/sse` | MCP SSE transport |
| POST | `/mcp/messages` | MCP message handler |
 
## Testing
 
Tests are organized under `tests/` mirroring `src/` structure. Uses vitest with MSW for HTTP mocking.
 
```bash
pnpm test
```