┌─────────────────────────────────────────────────────────────────────────┐
│ USER INTERFACE (React) │
│ Hosted on Vercel │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ User visits app
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION LAYER │
│ Supabase Auth │
│ • Login/Register │
│ • JWT token management │
│ • Session handling │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Authenticated
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PRACTICE SESSION START │
│ │
│ Frontend displays: │
│ • Target sentence: "Think about the weather" │
│ • [Optional] Play TTS example (ElevenLabs) │
│ • Record button │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ User clicks "Record"
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AUDIO CAPTURE (Frontend) │
│ │
│ Web Audio API + MediaRecorder API │
│ • Start recording from microphone │
│ • Real-time waveform visualization (WaveSurfer.js) │
│ • User speaks: "Fink about the wedder" │
│ • Stop recording │
│ • Convert to WAV/MP3 format │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ POST /api/v1/practice/submit-audio
│ Payload: { audio: File, reference_text: "..." }
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ BACKEND API (FastAPI) │
│ Hosted on Railway │
│ │
│ 1. Validate request (auth token, file size, format) │
│ 2. Upload audio to storage │
│ 3. Initialize session tracking │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Audio file ready
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AUDIO PREPROCESSING LAYER │
│ │
│ Python libraries: pydub, soundfile │
│ • Normalize audio volume │
│ • Remove leading/trailing silence │
│ • Resample to 16kHz (standard for speech) │
│ • Convert to required format │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Preprocessed audio
▼
┌──────────────────────┴──────────────────────┐
│ │
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────────┐
│ WHISPER API (OpenAI) │ │ AZURE SPEECH SERVICES │
│ │ │ Pronunciation Assessment │
│ • Transcription │ │ │
│ • Word-level timestamps │ │ Input: │
│ • Confidence scores │ │ • Audio file │
│ │ │ • Reference text: │
│ Returns: │ │ "Think about the weather" │
│ "Fink about the wedder" │ │ │
└────────────┬─────────────┘ │ Returns: │
│ │ • Overall accuracy: 68/100 │
│ │ • Phoneme-level scores: │
│ │ - θ → f (score: 31) │
│ │ - ð → d (score: 38) │
│ │ • Word-level breakdown │
│ │ • Error types │
│ └──────────────┬───────────────┘
│ │
│ │
└─────────────────┬─────────────────────────┘
│
│ Both results combined
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ERROR ANALYSIS ENGINE (Backend) │
│ Python + Business Logic │
│ │
│ 1. Compare Whisper transcription vs reference text │
│ 2. Parse Azure phoneme scores │
│ 3. Identify error patterns: │
│ • Phoneme substitutions (θ→f, ð→d) │
│ • Omissions │
│ • Timing/duration issues │
│ • Prosody problems │
│ │
│ 4. Query user history from database: │
│ • Past phoneme performance │
│ • Improvement trends │
│ • Recurring error patterns │
│ │
│ 5. Classify impediment type: │
│ • Frontal lisp (θ→f, ð→d pattern) │
│ • Rhotacism (r→w) │
│ • Etc. │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Structured error report
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ DATABASE UPDATE (Supabase) │
│ PostgreSQL │
│ │
│ INSERT INTO phoneme_performance: │
│ • user_id, session_id, timestamp │
│ • phoneme, accuracy_score, error_type │
│ • word, position │
│ │
│ UPDATE user_progress: │
│ • sessions_completed++ │
│ • overall_score_trend │
│ • current_difficulty_level │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Data saved
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AI FEEDBACK GENERATION (Claude API) │
│ Anthropic Claude Sonnet 4 │
│ │
│ Input payload: │
│ { │
│ "target_sentence": "Think about the weather", │
│ "user_transcription": "Fink about the wedder", │
│ "phoneme_errors": [ │
│ {"phoneme": "θ", "actual": "f", "score": 31, "word": "think"}, │
│ {"phoneme": "ð", "actual": "d", "score": 38, "word": "the"} │
│ ], │
│ "historical_patterns": { │
│ "θ_substitution_rate": 0.87, │
│ "sessions_completed": 12, │
│ "improvement_trend": "slight" │
│ }, │
│ "user_difficulty_level": 2 │
│ } │
│ │
│ Claude analyzes and generates: │
│ • Personalized, encouraging feedback │
│ • 5 adaptive practice sentences (progressive difficulty) │
│ • Specific articulation tips │
│ • Difficulty adjustment recommendation │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Claude response received
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ TEXT-TO-SPEECH GENERATION (ElevenLabs) │
│ Optional Step │
│ │
│ If user needs to hear correct pronunciation: │
│ • Generate TTS for problem words: "think", "the", "weather" │
│ • Generate TTS for next practice sentences │
│ • Use appropriate accent (en-US, en-GB, etc.) │
│ • Store audio URLs │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ TTS audio ready
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ RESPONSE ASSEMBLY (Backend) │
│ │
│ Compile complete response: │
│ { │
│ "session_id": "uuid", │
│ "overall_score": 68, │
│ "accuracy_breakdown": { │
│ "pronunciation": 65, │
│ "fluency": 82, │
│ "completeness": 100 │
│ }, │
│ "errors": [ │
│ { │
│ "phoneme": "θ", │
│ "word": "think", │
│ "score": 31, │
│ "feedback": "Try placing tongue between teeth" │
│ } │
│ ], │
│ "ai_feedback": { │
│ "text": "Good effort! I noticed you're substituting...", │
│ "encouragement": "You're making progress on fluency!" │
│ }, │
│ "practice_sentences": [ │
│ "The cat is here.", │
│ "I think that's right.", │
│ "This thing is smooth.", │
│ "Three brothers thought about it.", │
│ "The weather is thoroughly unpredictable." │
│ ], │
│ "tts_urls": { │
│ "correct_example": "https://storage.../correct.mp3", │
│ "practice_1": "https://storage.../p1.mp3", │
│ }, │
│ "visual_data": { │
│ "phoneme_chart": [...], │
│ "waveform_data": [...], │
│ "progress_history": [...] │
│ } │
│ } │
└────────────────────────────────┬────────────────────────────────────────┘
│
│ Return response to frontend
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ FRONTEND RESULTS DISPLAY │
│ │
│ User sees: │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Your Score: 68/100 │ │
│ │ ⭐⭐⭐☆☆ │ │
│ │ │ │
│ │ Great effort! I noticed you're substituting 'th' │ │
│ │ sounds with 'f' and 'd'. This is very common and │ │
│ │ completely fixable with practice. │ │
│ │ │ │
│ │ Problem Areas: │ │
│ │ 🔴 "think" - θ sound (31/100) │ │
│ │ [Play Correct] [Play Your Recording] │ │
│ │ │ │
│ │ 💡 Tip: Place your tongue between your teeth and │ │
│ │ blow air gently... │ │
│ │ │ │
│ │ 📊 Progress Chart [Recharts visualization] │ │
│ │ │ │
│ │ Next Practice Sentences: │ │
│ │ 1. "The cat is here." [▶️ Listen] [🎤 Record] │ │
│ │ 2. "I think that's right." [▶️ Listen] [🎤 Record] │ │
│ │ ... │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
│ User continues practice
▼
[Loop back to top]
┌──────────────┐
│ USER │
└──────┬───────┘
│
│ 1. Speaks into microphone
▼
┌──────────────────────┐
│ Web Audio API │
│ (Browser) │
│ • Capture audio │
│ • Real-time visual │
└──────┬───────────────┘
│
│ 2. Audio blob (WAV/MP3)
▼
┌──────────────────────┐
│ React Frontend │
│ • FormData prep │
│ • Loading states │
└──────┬───────────────┘
│
│ 3. HTTP POST with audio file + metadata
▼
┌──────────────────────────────────────────────────────────┐
│ FastAPI Backend (Railway) │
│ │
│ Rate Limiting → Auth Check → File Validation │
└──────┬───────────────────────────────────────────────────┘
│
│ 4. Save audio to storage
▼
┌──────────────────────┐
│ Supabase Storage │
│ • Store audio file │
│ • Generate URL │
└──────┬───────────────┘
│
│ 5. Audio URL
▼
┌──────────────────────────────────────────┐
│ Parallel API Calls │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Whisper │ │ Azure │ │
│ │ (STT) │ │ (Assess) │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ │ │ │
└─────────┼────────────────────┼───────────┘
│ │
│ 6. Transcription │ 7. Phoneme scores
│ │
└────────┬───────────┘
│
▼
┌────────────────┐
│ Error Analysis │
│ (Python Logic) │
└────────┬───────┘
│
│ 8. Error patterns identified
▼
┌────────────────┐
│ PostgreSQL │
│ (Supabase) │
│ • Save results │
│ • Get history │
└────────┬───────┘
│
│ 9. Historical data + current errors
▼
┌────────────────┐
│ Claude API │
│ • Generate │
│ feedback │
│ • Create │
│ sentences │
└────────┬───────┘
│
│ 10. Personalized response
▼
┌────────────────┐
│ ElevenLabs │
│ (Optional) │
│ • TTS for │
│ examples │
└────────┬───────┘
│
│ 11. Audio URLs
▼
┌────────────────┐
│ JSON Response │
│ Assembly │
└────────┬───────┘
│
│ 12. Complete response object
▼
┌────────────────┐
│ React Frontend │
│ • Display UI │
│ • Update state │
│ • Show results │
└────────────────┘
┌─────────────────────────────────────────────────────────┐
│ SUPABASE (All-in-One) │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ ┌─────────────────────┐ │
│ │ PostgreSQL DB │ │ Storage Buckets │ │
│ │ │ │ │ │
│ │ Tables: │ │ Buckets: │ │
│ │ • users │ │ • audio-uploads/ │ │
│ │ • sessions │ │ • tts-generated/ │ │
│ │ • phoneme_performance│ │ │ │
│ │ • practice_sentences│ │ Auto-delete after │ │
│ │ • user_progress │ │ 30 days (GDPR) │ │
│ │ • impediment_profiles│ │ │ │
│ └──────────┬───────────┘ └─────────┬───────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Supabase Realtime (Optional) │ │
│ │ • Live progress updates │ │
│ │ • Multi-device sync │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Supabase Auth │ │
│ │ • JWT tokens │ │
│ │ • Row-level security │ │
│ │ • OAuth providers │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ React + TypeScript + Tailwind + shadcn/ui │
│ Hosted on: Vercel │
└─────────────────────────┬────────────────────────────────────┘
│
│ HTTPS/WebSocket
▼
┌──────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ FastAPI (Python 3.11+) │
│ Hosted on: Railway/Render │
└─────────────────────────┬────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ AI Layer │ │ Data Layer │ │ Storage Layer│
│ │ │ │ │ │
│ • Whisper │ │ • PostgreSQL │ │ • Supabase │
│ • Azure │ │ • Redis │ │ Storage │
│ • Claude │ │ (cache) │ │ • Cloudflare │
│ • ElevenLabs │ │ • Supabase │ │ R2 │
└──────────────┘ └──────────────┘ └──────────────┘