Files · Automated parent progress report generator for tutoring businesses

# Automated parent progress report generator for tutoring businesses
 
> Generate consistent, data-driven progress reports without relying on instructor write-ups.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Problem
 
The academic director at a tutoring center struggles to get instructors to submit regular progress reports for each student. Parents expect weekly updates, but instructors forget or produce inconsistent quality. The director ends up chasing instructors and manually compiling reports, which is unsustainable as the center grows. This leads to parent frustration and churn.
 
This recipe automates report generation from sparse session data using an LLM-powered document-pipeline, so consistent, data-driven reports are produced without requiring instructor write-ups.
 
## Architecture
 
The document-pipeline processes report generation through 7 stages:
 
```
POST /api/reports/generate
  │
  ├─ Stage 1 — Setup: initialize run ID, tracing span
  ├─ Stage 2 — Validate: Zod schema validation of input request
  ├─ Stage 3 — Analyze: LLM-driven analysis of student performance data
  ├─ Stage 4 — Generate: narrative report sections via Vercel AI SDK
  ├─ Stage 5 — Assemble: structured Runbook with table of contents
  ├─ Stage 6 — Validate: completeness check + progress report validation
  └─ Stage 7 — Format & persist: Markdown export + JSON file storage
```
 
## Getting started
 
```bash
cp .env.example .env          # copy environment variables
# Edit .env and add your OPENAI_API_KEY
pnpm install                  # install dependencies
pnpm dev                      # start Next.js dev server
pnpm test                     # run vitest suite with coverage
```
 
## API Reference
 
| Endpoint | Method | Description |
|---|---|---|
| `/api/reports/generate` | POST | Submit student session data and generate a progress report |
| `/api/reports` | GET | List all previously generated reports |
| `/api/reports/:id` | GET | Retrieve a specific report by report ID |
| `/api/health` | GET | Health check endpoint |
 
### POST /api/reports/generate
 
Request body:
 
```json
{
  "student": {
    "studentId": "stu-001",
    "name": "Alice Smith",
    "grade": "5th",
    "subjects": [
      {
        "subject": "Math",
        "instructor": "Mr. Jones",
        "sessions": [
          {
            "date": "2026-01-15",
            "durationMinutes": 60,
            "topics": ["Algebra"],
            "attendance": "present",
            "performance": "good"
          }
        ],
        "goals": ["Improve algebra skills"]
      }
    ]
  },
  "periodStart": "2026-01-01",
  "periodEnd": "2026-01-31"
}
```
 
Response: `201 Created` with the generated `ProgressReport` JSON.
 
## REAA packages
 
| Package | Role |
|---|---|
| `@reaatech/agent-runbook` | Shared domain types, Zod schemas, UUID generation, retry, and error classes |
| `@reaatech/agent-runbook-agent` | LLM-powered analysis agent for student performance data |
| `@reaatech/agent-runbook-runbook` | Runbook assembly pipeline with completeness validation, TOC generation, and multi-format export |
| `@reaatech/agent-runbook-observability` | Structured logging (Pino), OpenTelemetry tracing, and Prometheus metrics |
| `@reaatech/agents-markdown` | Document validation types (`ValidationResult`, `Finding`, `LintResult`) and shared utilities |
| `@reaatech/agents-markdown-reporter` | Multi-format output reporters for console, JSON, HTML, and Markdown |
 
## Tech stack
 
- **Next.js 16+** (App Router) — API route handlers with `NextRequest`/`NextResponse`
- **TypeScript** — strict mode, full type safety across the pipeline
- **Vercel AI SDK v6** — provider-agnostic LLM interface with `@ai-sdk/openai`
- **Zod v4** — runtime schema validation for all domain types
- **Vitest** — test runner with v8 coverage (90%+ thresholds)
- **MSW** — HTTP mocking for integration tests
- **pnpm** — package manager (v10)
 
## Project layout
 
```
app/api/reports/       Next.js App Router API routes
src/types/             Domain types and Zod schemas
src/services/          Business logic: pipeline, LLM, validation, observability
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).