LinguaVibe Platform Requirements Document
LV
Engineering PRD • System Specification
LinguaVibe AI Platform Specs
v1.0.0 • Approved
Target: 2026-10-23
Executive Summary Mobile-First Hybrid Engine
LinguaVibe is an enterprise-grade, mobile-first AI language tutoring platform engineered with a signature deep-blue and crimson aesthetic. It delivers conversational immersion via dual-provider LLM orchestration (OpenAI & Anthropic Claude), real-time STT/TTS voice piping, owner-governed CMS course publishing, protected video streaming, and modular advertising hooks—all deployable as a responsive PWA with native iOS/Android compilation targets.
Target Tech Stack Matrix
Frontend Client: Next.js 14+ / React PWA + Tailwind
Mobile Wrapper: Capacitor 6 (iOS & Android)
Backend / API: Node Edge Runtime + Server Actions
Primary Database: PostgreSQL (Supabase / Prisma ORM)
AI Intelligence: OpenAI GPT-4o + Claude 3.5 Sonnet
Media Storage: Cloudflare R2 / AWS S3 + CDN
Role-Based Access (RBAC)
Learner (End User) Standard
Access to free/enrolled courses, interactive exercises, personal AI tutor, video catalog, and progress dashboard.
Platform Owner / Admin SuperAdmin
Exclusive access to Course CMS, Video upload pipeline, AI Provider Router, Ad Switchboard, and telemetry.
Visual Design Tokens (Red & Blue Specification)
Apple Music Usability Archetype
Deep Blue
#0A192F / Primary
Headers, Nav & Cards
Vibrant Red
#DC2626 / Accent
CTAs, Active, Badges
Dark Navy
#020617 / Dark Base
Dark Mode Background
Light Slate
#F8FAFC / Light Base
Card Backgrounds
Mobile UX Principles: Thumb-zone optimized bottom bar with 56px minimum tap targets. 16px base font size to eliminate auto-zoom on iOS Safari. Generous 12px-16px card border-radii with subtle micro-drop shadows for card elevate states.
Phase 1 Scope Boundaries
In-Scope (MVP Phase 1)
- Dual-provider AI text & turn-taking voice tutor
- 5-tab Apple Music style fixed bottom navigation
- Hierarchical courses (English, Spanish, French, etc.)
- Owner zero-code lesson & video CMS
- Advertising toggle infrastructure (disabled by default)
Explicit Non-Goals (Phase 1)
- Live human 1-on-1 video tutoring marketplace
- Native compiled binaries on Day 1 (uses PWA wrapper first)
- Hardcoded API keys or unvetted client-side secrets
- Mandatory ad monetization before user threshold
LinguaVibe Platform PRD • Confidential & Proprietary Section 1: Architectural Foundation • Page 1 of 5
MODULE 01 & 02
AI Language Tutor & Bottom Navigation Specs
Priority: P0 (Critical Path)
1. AI Language Tutor Engine (Text & Two-Way Voice)
CORE VALUE PROP
Dual-Provider Fallback Router
Backend edge handler routes requests to primary provider (OpenAI GPT-4o / Realtime API). On HTTP 429/500/timeout (>4500ms), system seamlessly switches to Anthropic Claude 3.5 Sonnet with identical conversation state.
POST /api/tutor/chat { lang: "fr", level: "B1", message: "...", historyId: "..." }
Voice Pipeline & Barge-In Audio
Client records via Web Audio API • Streamed STT via OpenAI Whisper API • Streaming LLM token generation • TTS output via OpenAI tts-1 (alloy/echo voices) • Visual pulse visualizer • Instant stop/interrupt ("barge-in") support.
No fake recordings: Real-time dynamic audio synthesis with audio playback cancellation.
Module 1 Acceptance Criteria (Gherkin Format)
| ID | Feature Scenario | Verification Criteria (Pass / Fail) |
|---|
| AC-AI-01 | CEFR Level Adaptation | Given learner selects "A1 - Spanish", AI responses must use simple present tense, provide bracketed English vocabulary hints, and keep sentences under 10 words. |
| AC-AI-02 | Constructive Correction | When user submits a grammar error, tutor outputs: 1) Gentle encouragement, 2) Highlighted correction card, 3) Cultural/grammatical rationale, 4) Follow-up conversational question. |
| AC-AI-03 | Voice Turn-Taking | Tapping mic activates audio stream; pausing speech for 1.2s auto-commits prompt; AI replies via synthesized speech while animating audio waveform. |
| AC-AI-04 | Audio Interruption | When AI audio is playing, tapping the screen or speaking instantly terminates audio playback buffer without crashing state or dropping conversational thread. |
| AC-AI-05 | Provider Failover | Simulating OpenAI 500 error causes automatic transparent retry to Anthropic Claude within 800ms with zero prompt truncation or user session loss. |
2. 5-Tab Fixed Bottom Navigation & Dashboard
UX ARCHITECTURE
1. Home
Dashboard & Streaks
2. Learn
Courses & Units
3. AI Tutor
Voice & Text
4. Videos
Official Lessons
5. Profile
Saved & Settings
Acceptance Criteria (AC-NAV-01): Bottom navigation bar remains pinned to bottom viewport with z-index: 50, incorporating env(safe-area-inset-bottom) for notched iOS and gesture-nav Android phones.
Acceptance Criteria (AC-NAV-02): Active tab exhibits Vibrant Red icon/label fill (#DC2626) with smooth 150ms opacity transition; inactive tabs render in muted slate-400.
Acceptance Criteria (AC-NAV-03): State preservation: Navigating between tabs retains unsubmitted chat drafts, video timestamp positions, and active quiz question indices without reload.
LinguaVibe Platform PRD • Confidential & Proprietary Section 2: Conversational Engine & Shell • Page 2 of 5
MODULE 03 & 04
Curriculum Engine, Quizzes & Learner Data Model
Priority: P0 (Core Foundation)
3. Structured Course & Interactive Exercise Engine
CURRICULUM ARCHITECTURE
The curriculum hierarchy is modeled as: Language → Level (Beginner A1/A2, Intermediate B1/B2, Advanced C1/C2) → Unit → Lesson → Activities.
Listening Drill
Audio playback at 1.0x / 0.75x speed with phoneme selection.
Multiple Choice
Grammar & context options with instant explanatory feedback.
Sentence Scramble
Reorder tokenized syntax chips into grammatically correct sentence.
Free-Form Writing
Open writing prompt scored by LLM for semantic accuracy.
Pronunciation Match
Learner speaks phrase; STT evaluates acoustic match percentage.
AI Practice Gen
Owner-tagged "Generate Drill" button spins on-the-fly exercises.
Acceptance Criteria (AC-CRS-01 to 03):
- AC-CRS-01 (Progress Resume): Launching a course resumes at the exact sub-lesson index left unfinished. Completed lessons display emerald checkmark badge.
- AC-CRS-02 (AI Labeling): Practice drills generated dynamically by the AI must display an unmistakable AI Generated pill to distinguish from official owner curriculum.
- AC-CRS-03 (Quiz Pass Threshold): End-of-unit tests require 80% passing grade to unlock sequential unit; failed attempts show targeted review recommendations.
4. Accounts, Security & Persistent Data Schema
DATA SPECIFICATION
Core Schema Entities (PostgreSQL / Prisma):
User: id, email, role (LEARNER|OWNER), createdAt
Profile: userId, targetLang, level, streakCount, lastActive
LessonProgress: id, userId, lessonId, score, completedAt
SavedVocabulary: id, userId, term, translation, context, memorized
ChatSession: id, userId, targetLang, provider, messages: JSONB
Authentication & Privacy Safeguards:
• Auth Modalities: Email/Password with Argon2 hashing + OAuth (Google/Apple) session tokens via HTTP-only secure cookies.
• Data Persistence: All user progress, streaks, and tutor conversation histories saved to remote DB; no ephemeral local-storage wipeout on browser refresh.
• Account Deletion (GDPR/CCPA): One-click "Delete My Account" permanently cascades user record, chats, and progress within 24 hours.
Acceptance Criteria (AC-AUTH-01): Password reset flow sends one-time cryptographic token valid for 15 minutes; rate-limited to 3 attempts/hour per IP.
LinguaVibe Platform PRD • Confidential & Proprietary Section 3: Curriculum & Data Architecture • Page 3 of 5
MODULE 05, 06 & 07
Owner Control Center, Video Hub & Ad Switchboard
Priority: P0 / P1
5. Protected Owner Administration & Content CMS
ZERO-CODE PUBLISHING
The Owner Dashboard (/admin) is locked down via server-side session claims. Client-side URL hiding is strictly prohibited as a security boundary.
Lesson Visual Builder
Add/edit courses, reorder modules via drag-drop, attach vocabulary cards, set pass criteria, preview instant mobile draft.
AI Provider Switcher
Toggle default LLM (OpenAI vs Anthropic), select models (e.g. gpt-4o-mini), adjust temperature & prompt injection guards.
Secure Secret Vault
Owner injects API credentials via encrypted server settings. Zero secrets exposed in browser client code or window bundles.
Acceptance Criteria (AC-CMS-01): Publishing or updating a lesson immediately propagates to all active mobile clients within 3 seconds via CDN cache invalidation, with zero app store rebuilds required.
Acceptance Criteria (AC-CMS-02): Draft mode maintains complete un-published state with side-by-side phone emulation preview.
6. Video Lessons Pipeline & Video Hosting Architecture
STREAMING SPEC
Video Storage & Streaming Hierarchy:
To keep hosting costs near $0 for launch, video is decoupled from DB:
- Tier 1 (Recommended Launch): Cloudflare Stream or unlisted authenticated Vimeo/YouTube embeds (avoids bandwidth bill shocks).
- Tier 2 (Pro Growth): Cloudflare R2 direct MP4/HLS storage + BunnyCDN with signed HLS tokens.
- Player UX: Custom HTML5 video wrapper with scrub bar, 10s skip, playback speed (0.75x-1.5x), and VTT caption track renderer.
Owner Video Controls & Criteria:
• AC-VID-01 (Metadata): Owner uploads video with title, language tag, CEFR level badge, custom thumbnail, and optional WebVTT subtitles.
• AC-VID-02 (Telemetry): System records learner view milestones (25%, 50%, 75%, 100%) to mark video lesson completion.
• AC-VID-03 (Permissions): Video download URLs are obfuscated to discourage media scraping.
7. Advertising Switchboard & Placement Rules
DISABLED BY DEFAULT
1. Master Kill Switch
Global toggle completely suppresses all ad network scripts until explicitly enabled by owner.
2. Restricted Zones
Zero ads permitted in: Voice AI conversation screen, mic permission modals, or audio exercise loops.
3. Permitted Placements
Standard banners on Lesson Completed celebration screen, Video feed footer, and Course index bottom.
Acceptance Criteria (AC-AD-01): If an ad unit fails to load or provider triggers error, the container gracefully collapses to 0px height without breaking adjacent content layout.
LinguaVibe Platform PRD • Confidential & Proprietary Section 4: Administration & Monetization • Page 4 of 5
PLAN & ROADMAP
Security, Beginner Cost Analysis & 5-Stage Plan
Execution Blueprint
Beginner Infrastructure Cost Matrix (Launch to Scale)
Zero-Waste Architecture
| Service Category | Recommended Provider | MVP Launch Tier | Scaling Cost Trigger |
|---|
| Web Hosting & Serverless | Vercel / Cloudflare Pages | $0 / month (Hobby Tier) | $20/mo when exceeding 100GB bandwidth |
| Database & Auth | Supabase (PostgreSQL) | $0 / month (Free 500MB DB) | $25/mo when active users exceed 50,000 |
| AI LLM Text API | OpenAI (gpt-4o-mini) | Pay-as-you-go (~$0.15/1M tokens) | ~$5-$15/month for initial 100 learners |
| Voice STT & TTS | Whisper + OpenAI TTS-1 | $0.006/min STT + $0.015/1k chars | ~$10/month for 500 voice sessions |
| Video Hosting & CDN | Cloudflare Stream / R2 | $0 (R2 10GB free tier) | $5/mo + $1/1k mins streamed |
| App Store Accounts | Apple Developer + Google Play | Defer to Stage 5 | Apple: $99/yr • Google: $25 one-time |
Total estimated cost to build and pilot MVP: ≤ $10 - $25 total outlay.
5-Stage Phased Implementation Plan
Definition of Done (DoD)
STAGE 1 Mobile Foundation & Auth Setup
Build red-and-blue theme, responsive 5-tab bottom navigation, Supabase auth (login/register), home dashboard with daily goals & streaks.
DoD: Tested on mobile viewport
STAGE 2 AI Tutor Engine (Text + Real Voice)
Integrate OpenAI GPT-4o & Claude fallback; implement STT microphone input, audio streaming playback, barge-in interruption, and error toast handling.
DoD: Real 2-way voice chat
STAGE 3 Learning Content & Owner Video Library
Build course catalog (English, Spanish, French, etc.), interactive quiz player with 6 exercise modalities, and video player with progress markers.
DoD: End-to-end lesson completion
STAGE 4 Owner Administration & Ad Switchboard
Zero-code Lesson CMS, video management, secret credential key vault, and advertising controls with placement permissions.
DoD: Secure admin updates live content
STAGE 5 Cross-Device Testing & App Store Preparation
Rigorous mobile stress-testing, offline PWA service workers, Capacitor packaging configuration for Google Play and iOS App Store deployment.
DoD: Installable on iPhone & Android
Lead Systems Architect: Lenny • Full-Stack AI Engineer
Specification is ready for immediate sprint implementation.
READY FOR BUILD
LinguaVibe Platform PRD • Confidential & Proprietary Section 5: Roadmap & Verification • Page 5 of 5
