brian-chebon/tugen-app

# Tugen Language Learning App Learn the Tugen (Kalenjin) language through interactive phrases, vocabulary games, and cultural stories. ## Features - **Phrasebook**: Browse categorized phrases with native audio, Swahili & English translations - **Vocabulary Game**: Flashcards with FSRS spaced repetition, multiple-choice quizzes, gamification (XP, streaks, hearts, leaderboards) - **Interactive Stories**: Audio stories with synchronized transcripts, comprehension exercises - **Offline-First**: Full offline support with background sync - **Trilingual**: UI in English, Swahili, and Tugen ## Architecture ``` Feature-first Clean Architecture + Riverpod ├── core/ (audio, auth, database, network, supabase, sync, router, l10n, theme) ├── features/ (phrasebook, vocab_game, stories, user_progress, settings) └── shared/ (models, widgets, extensions) ``` **Key decisions:** - **State Management**: Riverpod (compile-safe, async-native) - **Local DB**: Drift (type-safe SQL, reactive streams, migrations) - **Auth**: Firebase Auth (email/password, anonymous, account linking) - **Database**: Supabase (PostgreSQL with Row Level Security) - **File Storage**: Firebase Storage (audio, images) - **Analytics**: Firebase Analytics - **Audio**: just_audio (gapless, clip playback, speed control) - **Spaced Repetition**: FSRS v4 via `fsrs` package (20-30% fewer reviews than SM-2) - **Background Sync**: workmanager + transactional outbox pattern ## Setup ### Prerequisites - Flutter SDK >= 3.24.0 - Dart >= 3.5.0 - Firebase CLI (`npm install -g firebase-tools`) - A Supabase project (supabase.com) - Android Studio / Xcode ### Steps 1. **Clone and install dependencies** ```bash git clone cd tugen_app flutter pub get ``` 2. **Configure Firebase (Auth, Storage, Analytics)** ```bash # Login to Firebase firebase login # Configure for your project flutterfire configure # This auto-generates lib/firebase_options.dart ``` 3. **Configure Supabase (Database)** ```bash # …