Polly/docs/EXERCISES.md

Vocabulary Exercises Documentation

This document explains how the exercise system works in the Polly vocabulary learning app.

Overview

The exercise system allows users to practice vocabulary through various interactive exercise types. Users can configure and start exercises from different screens, track their progress, and review their results.

Exercise Types

The app supports four different exercise types:

1. Guessing Exercise (Flashcard Mode)

How it works:

• A vocabulary card is displayed with one side (word or translation)
• The user sees only one side of the card initially
• The user guesses the answer before flipping the card

User actions:

• Tap "Flip Card" to reveal the answer
• Mark as "Wrong" or "Correct" after revealing
• The card advances when "Next" is tapped

Use case: Ideal for quick recognition practice and memorization.

---

2. Spelling Exercise

How it works:

• A vocabulary word is displayed as a prompt
• The user must type the translation manually
• The app checks if the typed answer is correct

User actions:

• Type the translation in the text field
• Tap "Check" to submit the answer
• See immediate feedback on correctness
• Tap "Next" to proceed to the next card

Use case: Excellent for practicing proper spelling and reinforcing memory through active recall.

---

3. Multiple Choice Exercise

How it works:

• A word is displayed with four answer options
• Only one option is the correct translation
• The user selects their answer

User actions:

• Tap one of the four options
• The correct answer is highlighted after selection
• Visual feedback shows if the choice was right or wrong
• Tap "Next" to continue

Use case: Good for recognition practice with immediate feedback.

---

4. Word Jumble Exercise

How it works:

• A word's letters are scrambled and displayed
• The user must click letters in the correct order to form the word
• Letters can be moved between the "available" and "assembled" areas

User actions:

• Click a letter from the available pool to add it to the assembly area
• Click an assembled letter to return it to the pool
• Tap "Check" when the word is assembled
• The correct answer is revealed if incorrect

Use case: Great for reinforcing spelling through active manipulation of letter order.

---

Starting an Exercise

Entry Points

1. Dashboard Widget: Tap "Start Exercise" from the ModernStartButtons widget
2. Category Detail Screen: Tap "Start" on a specific category
3. Main Vocabulary Screen: Tap the FAB (Floating Action Button)
4. Daily Exercise: Access from the dashboard for daily review

Configuration Options

Before starting an exercise, users can configure:

Option	Description
Number of Cards	Slider to select how many cards to practice (1 to total available)
Quick Select	Preset buttons for 10, 25, 50, or 100 cards
Language Direction	Choose origin and target languages
Exercise Types	Select which exercise types to include (can combine multiple)
Shuffle Cards	Randomize card order
Shuffle Languages	Randomize which side (word/translation) is shown
Training Mode	Practice without affecting progress/stages
Due Today Only	Limit to items scheduled for today

---

Exercise Flow

┌─────────────────┐
│   START SCREEN  │
│ (Configuration) │
└────────┬────────┘
         │ Tap "Start Exercise"
         ▼
┌─────────────────┐
│   EXERCISE      │
│   PROGRESS      │
│   INDICATOR     │
├─────────────────┤
│   CARD/QUESTION  │
│   DISPLAY       │
├─────────────────┤
│   CONTROLS      │
│ (Reveal/Check)  │
└────────┬────────┘
         │ Complete all cards
         ▼
┌─────────────────┐
│   RESULT SCREEN │
│   (Score,       │
│    Retry,       │
│    Start Over)  │
└─────────────────┘

---

Exercise Progress Indicator

During an exercise, a progress bar shows:

• Green section: Number of correct answers
• Red section: Number of wrong answers
• Total: Total cards in the exercise
• Close button: Exit the exercise (shows confirmation dialog)

The progress bar animates as the user advances through cards.

---

Exercise State Management

The app uses a state machine to manage exercise progress:

States

State	Description
START	Configuration screen before starting
EXERCISE	Active exercise in progress
RESULT	Exercise completed, showing results

State Transitions

START → EXERCISE (user taps "Start")
EXERCISE → RESULT (all cards completed)
RESULT → START (user taps "Start Over")
RESULT → EXERCISE (user taps "Retry Wrong")

---

Exercise Actions

The following user actions are available during exercises:

Action	Description
Reveal	Show the answer (Guessing exercise)
Submit	Submit an answer (Spelling, Multiple Choice, Word Jumble)
Next	Move to the next card
UpdateWordJumble	Modify assembled letters (Word Jumble)

---

Results Screen

After completing an exercise, users see:

Displayed Information

• Percentage Score: Overall performance as a circular progress indicator
• Correct/Wrong Count: Detailed breakdown of answers
• Total Items: Number of cards practiced

Available Actions

• Start Over: Begin a new exercise from scratch
• Repeat Wrong: Retry only the incorrectly answered cards
• Finish: Return to the main screen

---

Training Mode

When Training Mode is enabled:

• Answers are not recorded for progress tracking
• No stage progression occurs
• Useful for casual practice or testing knowledge

When disabled (default):

• Correct answers may advance item stages
• Progress is saved for statistics
• Affects due dates and learning progress

---

Technical Architecture

Key Components

1. VocabularyExerciseHostScreen.kt

   • Main container managing exercise flow
   • Handles screen states (START, EXERCISE, RESULT)
   • Coordinates between configuration and exercise screens

2. VocabularyExercise.kt

   • Defines exercise types (enum)
   • State classes for each exercise type
   • Action sealed class for user interactions

3. VocabularyExerciseRenderer.kt

   • Renders the appropriate UI based on exercise state
   • Handles display logic for each exercise type

4. ExerciseControls.kt

   • Input field and buttons for user interaction
   • Different controls based on exercise type

5. ExerciseProgressIndicator.kt

   • Visual progress bar during exercises
   • Animated updates for correct/wrong counts

---

Related Screens

Screen	Purpose
StartScreen	Configure exercise settings before starting
ResultScreen	Show final score and options to continue
CategoryDetailScreen	Start exercise for a specific category
DashboardContent	Main dashboard with exercise shortcuts

---

Tips for Users

1. Combine exercise types: Mix Guessing, Spelling, and Word Jumble for variety
2. Use Training Mode: For casual practice without affecting progress
3. Start small: Use 10-25 cards initially, increase as comfortable
4. Review wrong answers: Use "Repeat Wrong" to focus on difficult items
5. Daily exercises: Use "Due Today Only" for spaced repetition practice

---

Navigation During Exercise

• Close button: Exit exercise (confirms before closing)
• Back button: Also triggers exit confirmation
• Results screen options: Continue practicing or return to dashboard