Lao Language Learning App Development

Expert guidance for working with a Flutter application designed to teach the Lao language through interactive exercises including letter recognition, sound matching, and visual exercises.

Architecture Overview

The app follows a layered architecture pattern:

**Presentation Layer** (pages, components) → **Business Logic** (exercises, lesson generation) → **Data Layer** (utilities, Hive storage)

Key structural components:

Development Workflow

Standard Commands

When working with this Flutter project, use these commands:

1. **Running the app**: Always use `flutter run` for debugging (never `flutter build`). If no emulator is open, launch the medium-sized emulator first.

2. **Installing dependencies**: Run `flutter pub get` after any pubspec.yaml changes

3. **Code formatting**: Use `dart format .` to format the entire codebase with Dart standards

4. **Static analysis**: Run `flutter analyze` to check for code issues

5. **Testing**: Use `flutter test` for unit tests, add `--coverage` flag for coverage reports

6. **Cleaning build artifacts**: Run `flutter clean` when encountering build issues

Navigation Structure

The app uses bottom navigation via the DefaultPage widget:

Exercise System

Exercise Base Pattern

All exercises inherit from the `StatefulExercise` abstract class with these key features:

1. **Unique Key Generation**: Each exercise receives `UniqueKey()` to ensure proper widget rebuilding

2. **Bottom Sheet Feedback**: `showBottomBar()` displays user feedback with onShow/onHide callbacks

3. **Abstract Methods**: `bottomSheetContent()` and `build()` must be implemented by subclasses

Exercise Types

Adding New Exercises

When creating a new exercise type:

1. Create a class extending `StatefulExercise`

2. Implement `bottomSheetContent()` for feedback UI

3. Implement `build()` for the main exercise UI

4. Add the exercise to lesson generation in `LessonGenerator.generateLesson()`

5. Ensure the exercise calls `context.read<LessonProvider>().nextExercise()` upon completion

Lesson Generation System

**LessonGenerator** (lesson_generators/lesson_generator.dart) creates pedagogical lesson sequences:

1. Introduction to new consonants/vowels

2. Exercise pairs (SelectSound + SelectLetter for newly learned letters)

3. Matching exercises (all currently learned letters)

4. Spelling exercises (using learned letters)

5. Review matching exercises

**LessonData** (utilities/lesson_data.dart):

**LetterData** (utilities/letter_data.dart):

State Management

Provider Pattern

Hive Persistence

Storage boxes:

**HiveUtility** provides convenience methods:

**Reactive Updates**: HomePage uses `ValueListenableBuilder` on Hive box for real-time lesson status updates

Audio System

**AudioUtility** provides three main methods:

1. **playLetter(Letter)**: Plays consonant audio from `assets/consonants/sounds/{romanization}.wav` or vowel audio from `assets/vowels/sounds/{index}.wav`

2. **playSoundEffect(String)**: Plays UI feedback sounds (correct/incorrect/complete)

3. **playWord(String)**: Plays word pronunciation from `assets/words/{word}.mp3`

Uses AudioPlayer singleton with AssetSource for all audio playback.

Asset Organization

```

assets/

├── consonants/

│ ├── images/ # SVG/PNG images for consonants

│ └── sounds/ # WAV audio files for consonant pronunciation

├── vowels/

│ └── sounds/ # WAV audio files for vowel pronunciation

├── words/ # MP3 files for word pronunciation

├── sound_effects/ # Correct/incorrect/complete WAV files

└── fonts/NotoSansLaoLooped/ # Lao-specific font files

```

Adding Audio Assets

Follow these conventions:

Adding New Letters

When adding new Lao letters to the curriculum:

1. Add the letter definition to `LetterData` (in consonant teaching order or vowel mapping)

2. Add the pronunciation audio file to the appropriate `assets/` directory

3. Update `LessonGenerator` to include the new letter in the appropriate lesson position

4. Add corresponding images/icons to assets if needed

Key Dependencies

| Package | Purpose |

|---------|---------|

| provider | State management (ThemeProvider, LessonProvider) |

| audioplayers | Audio playback for pronunciation and UI feedback |

| hive_flutter | Local database for lesson completion and settings |

| confetti | Celebration animations on lesson completion |

| fluttertoast | Toast notifications for user feedback |

| collection | Utility functions (e.g., shuffling) |

| haptic_feedback | Vibration feedback for interactions |

| flutter_svg | SVG rendering support |

Important Guidelines

1. **Always use run mode** instead of build mode when debugging

2. **Never skip code formatting**: Run `dart format .` before committing

3. **Unique keys are critical**: All exercises must use `UniqueKey()` for proper rebuilding

4. **Audio file naming matters**: Follow strict naming conventions for audio assets

5. **Provider context**: Always use `context.read<LessonProvider>()` for navigation callbacks

6. **Hive box names**: Use 'lesson_completion' and 'settings' exactly as specified

7. **Asset paths**: Maintain the exact directory structure for audio and images