keen-app

As a user I want to see visual mouth position guides for difficult phonemes so I can learn correct articulation. Implement a backend API endpoint that returns mouth position illustration data or SVG descriptors per phoneme. Integrate Google Nano Banana or equivalent to generate visual guides for French phonemes.

As a user I want to save and manage my favorite words so I can quickly revisit them for further practice. Implement FastAPI endpoints to add, remove, and list saved/favorite words per user. Each saved word entry stores the word ID, last accuracy score, and revisit flag. Support sorting by accuracy (lowest first) for the revisit queue.

As a user I want to hear the correct French pronunciation of any word via text-to-speech so I can learn the right sound before recording. Implement a backend FastAPI endpoint that accepts a French word and returns TTS audio. Integrate Google TTS or equivalent for natural French pronunciation. Support normal and slow playback speeds.

As a user I want to browse and practice French tongue twisters with difficulty metadata so I can target specific sounds. Implement FastAPI endpoints to list tongue twisters with fields: text, difficulty level, target phonemes/sounds, category, and point reward. Support filtering by difficulty. Pre-seed with at least 10 tongue twisters including 'Les chaussettes de l'archiduchesse'.

As a user I want to experience the interactive French Café landing page so I can navigate to all main features. Implement the Home page based on the existing v3 JSX design. Includes: animated café background (steam, waiter, bokeh), NavBar with glass-morphism, HeroCafeScene (full viewport), DailyStreakBanner (gold gradient), CafeMenuGrid (Practice Words, Daily Challenge, Tongue Twisters, Progress), DailyChallengeFeature card, ProgressSnapshot, TongueTwisterTeaser (café bookshelf), SavedWordsFavorites, HowItWorks, MotivationalCTA, and Footer with Parisian silhouette SVG.

As a user I want my practice streaks and accuracy history to be tracked and persisted so I can see my improvement over time. Implement FastAPI endpoints for: recording daily practice sessions, calculating consecutive streak days, aggregating accuracy scores over time (7-day sparkline data), and returning words mastered count. Use IST timezone for streak calculations.

As a user I want to record my pronunciation and receive accuracy analysis so I can understand how close my speech is to native French. Implement a backend FastAPI endpoint that accepts audio input, runs speech recognition, and returns an overall accuracy score plus per-phoneme breakdown scores. Integrate with a suitable speech recognition service (e.g., Google Speech-to-Text or similar).

As a user I want to practice French word pronunciation so I can improve my spoken French. Implement the Practice page based on the existing v3 JSX design. Includes: PracticeNavBar, PracticeSessionHeader (category/word count/XP), WordDisplayCard (large serif word display, IPA transcription, TTS listen button, bookmark), PronunciationRecorder (mic button with idle/recording/processing states, waveform visualizer), FeedbackPanel (score with count-up animation, AI feedback summary, Try Again / Next Word CTAs), SoundAnalysisBreakdown (phoneme chips with accuracy dots), MouthPositionGuide, CommonMistakesTips (notepad style), WordNavigationControls (prev/next + progress bar + dot pagination), SaveAndProgressBar, and PracticeFooter.

As a user I want to browse and practice French tongue twisters so I can improve specific pronunciation sounds. Implement the Tongue Twisters page based on the existing v3 JSX design. Includes: NavBar (Tongue Twisters active), TongueTwisterHero (animated headline, illustrated book, Start Twisting CTA), DifficultyFilterBar (Débutant/Intermédiaire/Avancé pills + search), FeaturedTwisterCard (chalkboard style, full twister text, play button, difficulty stars, point reward, countdown), TwisterBrowseGrid (glassmorphism cards, difficulty badges, category tags, personal best), ActivePracticeStudio (listen/record/replay buttons, waveform visualizer, speed control), SoundBreakdownPanel (score donut, phoneme chips, try again/save), StreakProgressBar (gold banner, flame, pip row, daily completion counter), RevisitDifficultQueue (horizontally scrollable chips), RelatedChallengesCTA, and Footer.

As a user I want to access and manage my saved favorite words so I can quickly revisit and practice them. Implement the Saved Words page based on the existing v3 JSX design. Includes: saved word chips/cards with pronunciation score indicators (green/amber/red), replay icon per word, ability to remove words, empty state illustration, and a link back to Practice for any saved word. Links from Home SavedWordsFavorites section and Consistent learner flow.

As a user I want to receive one featured word challenge per day and earn points upon correct pronunciation so I can stay engaged. Implement a FastAPI endpoint that selects a daily challenge word (rotated daily, IST timezone), records user attempt results, awards points on success, and returns the next challenge countdown. Include a leaderboard-ready points accumulation endpoint.

As a user I want to view my learning progress and streaks so I can stay motivated. Implement the Progress page based on the existing v3 JSX design. Includes: streak display with flame animation, accuracy improvement graphs, words mastered count, 7-day sparkline bar chart, circular accuracy ring, and revisit queue for difficult words. Page links from Home CafeMenuGrid and from Casual/Consistent learner flows.

As a user I want to complete a daily pronunciation challenge so I can earn points and maintain my streak. Implement the Daily Challenge page based on the existing v3 JSX design. Includes: featured word of the day on a chalkboard-style card, IPA transcription, listen button, record button, point reward badge, difficulty indicator, countdown timer to next challenge, and result/celebration screen on completion. Links from Home DailyChallengeFeature section and Casual learner flow.

As a user I want to receive friendly, human-readable AI-generated feedback on my pronunciation so I know specifically what to improve. Implement a Langchain-based pipeline using GPT to generate contextual feedback from phoneme accuracy scores. Return a short encouragement message, specific mistake descriptions per phoneme, and actionable improvement tips tailored for Indian learners.

As a user I want my real progress stats and streak data to appear across the Home page, Progress page, and streak banners so I can see my actual improvement. Wire the ProgressSnapshot, DailyStreakBanner, StreakProgressBar (Tongue Twisters page), and Progress page to the Streak and Progress API. Animate score count-ups and streak pip fills on data load.

As a user I want to see detailed pronunciation feedback after recording so I can understand what to improve. Implement the Feedback page based on the existing v3 JSX design. Includes: TopBar (sticky, breadcrumb Practice > Grenouille > Feedback, save bookmark, share icon), WordResultHeader (large word + IPA + play button + difficulty badge), OverallScoreBanner (animated SVG score ring, color-coded tier band), PhonemeBreakdown (phoneme chip row with expand-on-click accuracy details), WaveformPlayback (side-by-side native vs user waveforms, similarity score), MouthPositionGuide (phoneme selector tabs, illustrated diagram), CommonMistakesPanel (amber-tinted frosted card, 3-4 mistake cards), ImprovementTips (3 tip cards with hover lift), and ActionFooterBar (Try Again, Next Word, Save Word).

As a user I want to view mouth and tongue position guides for specific French sounds so I can learn correct articulation. Implement the Guide page based on the existing v3 JSX design. Includes: phoneme selector pill tabs, illustrated mouth/tongue/lip position diagram per phoneme, labeled arrows for tongue placement and airflow, 'Common French sounds Indians find difficult' callout box, and a 2-3 line description per sound. Links from Practice FeedbackPanel and Feedback MouthPositionGuide section.

As a user I want the full practice loop (hear word → record → get phoneme feedback → see mouth guide → retry) to work end-to-end so I can have a seamless learning experience. Wire the Practice page and Feedback page frontend to the TTS, speech recognition, AI feedback, and mouth position guide APIs. Handle loading states, error states, and retry flows in the UI.