Relay

Relay is a between-lessons AI warmup for Preply.

The core idea is simple: before the next live class, the learner gets a short voice-based recap that checks what still sticks, boosts confidence, and briefs the tutor on where to start.

Why This Can Win

• It fits Preply directly: the product sits between real classes, not beside them.
• It gives a crisp live demo: paste notes, run a voice warmup, show one hero score, show the Tutor Brief.
• It is finishable today if scope stays tight.

Scope Locked For Today

Ship one hero loop by 16:00 CET:

1. Input lesson notes from the previous class.
2. Run a voice warmup in one of two lengths:
   • 3-minute Warmup
   • 1-minute Rush
3. Grade the answers and compute a Lesson Readiness Score.
4. Show a compact Tutor Brief with:
   • what stuck
   • what is shaky
   • where to start in the next class

Anything beyond that is stretch work.

Proposed Stack

• Frontend: Next.js + Tailwind CSS
• Hosting: Vercel first
• Realtime voice: Agora
• LLM + structured outputs: OpenAI
• Charts and metrics UI: Recharts
• Optional stretch only if the core is stable early:
  • avatar layer
  • extra sponsor integrations
  • AWS add-ons if they unblock something concrete

Warm-up Lobby Prototype (Current)

The web app now includes a call-style Warm-up Lobby UI for the "10 minutes before class" flow:

1. Learner gets an AI warm-up session before the tutor joins.
2. Session startup is routed through POST /api/agora/session.
3. Session stop is routed through DELETE /api/agora/session/:agentId.
4. If live Agora credentials are missing, the API automatically falls back to mock mode so demos still run.

Required env vars for live Agora mode

AGORA_APP_ID=
AGORA_CUSTOMER_ID=
AGORA_CUSTOMER_SECRET=
AGORA_LLM_URL=

Optional env vars

AGORA_APP_CERTIFICATE= # enables server-side RTC token generation
AGORA_AGENT_TOKEN= # optional if AGORA_APP_CERTIFICATE is set
AGORA_API_BASE_URL=https://api.agora.io
AGORA_AGENT_NAME=relay-warmup
AGORA_AGENT_RTC_UID=0
AGORA_LEARNER_TOKEN= # optional static token for browser RTC join
AGORA_ENABLE_RTM=true
AGORA_PIPELINE_ID= # optional; recommended for stable voice behavior
AGORA_LLM_API_KEY=
AGORA_LLM_VENDOR=custom
AGORA_LLM_STYLE=openai
AGORA_LLM_MODEL=gpt-5.4-mini
AGORA_GREETING_MODE=single_first
AGORA_GREETING_MESSAGE=
AGORA_TTS_VENDOR=openai
AGORA_TTS_KEY=
AGORA_TTS_VOICE_ID=alloy
AGORA_TTS_MODEL=gpt-4o-mini-tts
AGORA_TOKEN_TTL_SECONDS=3600
AGORA_GEOFENCE_AREA=
AGORA_GEOFENCE_EXCLUDE_AREA=
AGORA_JOIN_PROPERTIES_JSON=

Team Rules

• Before starting work: pull main, read project_context.md, and check the kanban.
• If using a coding agent, connect it to GitHub CLI or GitHub tools first so it can read the kanban before choosing a task.
• Prefer separate files and modules per lane to avoid merge conflicts.
• Finished beats perfect. Protect the happy path and backups before stretch ideas.

Build-Day Timeline

10:00-10:30 CET

• Freeze scope
• Confirm env vars and accounts
• Scaffold app
• Get a Vercel stub live early

10:30-11:30 CET

• Build note input
• Build extraction contract
• Build setup and session UI shell
• Build Agora start and stop path

Milestone: user can move from notes to a started session without dead ends.

11:30-12:30 CET

• Wire the voice loop
• Generate warmup questions for both lengths
• Capture answers and grade them

Milestone: one full warmup run works end to end.

12:30-13:30 CET

• Add Lesson Readiness Score
• Add Tutor Brief
• Add dashboard shell

Milestone: demo has a clear before-and-after outcome, not just a conversation.

13:30-14:30 CET

• Replace mocks with real outputs where safe
• Tighten prompts
• Improve the visual story of the hero score and brief

Milestone: demo looks intentional, not stitched together.

14:30-15:15 CET

• Add fallbacks for API failure, slow voice, or mic issues
• Capture screenshot and recording backups
• Lock the exact demo script

15:15-16:00 CET

• Full rehearsal only
• No risky new code
• Freeze on the last working build

Kanban And Shared Context

• Kanban: Preply Agora Hackathon plan
• Shared build state: project_context.md
• Longer source briefing: docs/relay-team-briefing.md

Suggested Parallel Lanes

• Lane 1: platform, env, deploy, API routing
• Lane 2: AI extraction, grading, scoring
• Lane 3: Agora voice session and session orchestration
• Lane 4: setup screen, session UI, dashboard, Tutor Brief

Current Tickets

• #1 Lane 1: bootstrap app, envs, and Vercel deploy
• #8 Lane 2: build extraction, warmup generation, and grading contract
• #7 Lane 3: wire Agora voice session and browser session loop
• #5 Lane 4: build setup screen and live session UI shell
• #6 Lane 4: build readiness dashboard and Tutor Brief card
• #2 Cross-cutting: keep project_context.md updated after merges
• #3 Cross-cutting: demo hardening and backup assets
• #4 Stretch only after the core loop is safe