Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Cristiang1021/ErgoKawsay/llms.txt
Use this file to discover all available pages before exploring further.
ErgoKawsay follows a feature-based architecture that cleanly separates concerns across four top-level namespaces inside lib/: core for shared utilities and infrastructure, data for models and repositories, features for screen-level UI organised by domain, and shared/widgets for reusable UI components. This layout keeps each feature self-contained, makes it straightforward to add or remove a module without touching unrelated code, and ensures the bilingual (Spanish / Kichwa) and offline-first constraints are enforced at well-defined boundaries.
Top-Level Directory
The repository root contains the Flutter project scaffolding plus the translation source file used to generate tr.dart:
ErgoKawsay/
├── lib/ # All Dart source code
├── assets/ # Audio, video, images, branding
├── android/ # Android-specific project files
├── ios/ # iOS project files (scaffold only)
├── web/ # Web scaffold (not shipped)
├── linux/ # Linux desktop scaffold
├── macos/ # macOS scaffold
├── windows/ # Windows scaffold
├── tools/ # Build-time scripts
├── translations.yaml # Source of truth for i18n strings
└── pubspec.yaml # Flutter package manifest
The app targets Android as its primary platform. The ios/, web/,
linux/, macos/, and windows/ scaffolds are generated by Flutter and are
not actively maintained or shipped.
lib/ Structure
Every Dart source file lives under lib/. The tree below lists all directories and files:
lib/
├── main.dart // Entry point — initialises StorageService,
│ // NotificationService, and runs ErgoKawsayApp
├── app.dart // ErgoKawsayApp StatefulWidget, route table,
│ // and Kichwa locale delegates
│
├── core/
│ ├── constants/
│ │ ├── app_constants.dart // Keys, app name, language codes, defaults
│ │ └── app_assets.dart // Typed asset path constants
│ ├── localization/
│ │ ├── tr.dart // Generated translation strings (do not edit)
│ │ ├── app_localizations.dart // AppLocalizations delegate + supported locales
│ │ ├── locale_controller.dart // ChangeNotifier for active Locale
│ │ ├── theme_controller.dart // ChangeNotifier for ThemeMode
│ │ └── accessibility_controller.dart // ChangeNotifier for AccessibilitySettings
│ ├── services/
│ │ └── notification_service.dart // flutter_local_notifications wrapper
│ ├── storage/
│ │ └── storage_service.dart // SharedPreferences wrapper (all persistence)
│ └── theme/
│ ├── app_theme.dart // ThemeData (light + dark)
│ ├── app_palette.dart // Raw colour palette
│ ├── app_colors.dart // Semantic colour tokens
│ ├── app_spacing.dart // Spacing scale constants
│ └── app_typography.dart // TextTheme definitions
│
├── data/
│ ├── local/
│ │ ├── local_data_repository.dart // Singleton — all static content getters
│ │ └── quiz_data.dart // Quiz question definitions
│ └── models/
│ ├── accessibility_settings.dart
│ ├── active_break_step.dart
│ ├── disease.dart
│ ├── emotion.dart
│ ├── exercise.dart // Also defines ExerciseCategory
│ ├── home_category.dart // HomeCategory enum (body, mind, today, learn)
│ ├── module_item.dart
│ ├── music_track.dart
│ ├── progress_data.dart
│ ├── quiz_question.dart
│ ├── reminder_settings.dart
│ ├── tip.dart
│ └── video_item.dart
│
├── features/
│ ├── active_breaks/
│ │ └── active_breaks_screen.dart
│ ├── diseases/
│ │ └── diseases_screen.dart
│ ├── emotions/
│ │ └── emotions_screen.dart
│ ├── ergonomics/
│ │ └── ergonomics_screen.dart
│ ├── exercises/
│ │ ├── exercises_screen.dart
│ │ └── exercise_session_screen.dart
│ ├── home/
│ │ └── home_screen.dart
│ ├── language/
│ │ ├── language_selection_screen.dart
│ │ └── splash_screen.dart
│ ├── music/
│ │ ├── audio_controller.dart // just_audio playback logic
│ │ ├── music_screen.dart
│ │ └── now_playing_screen.dart
│ ├── progress/
│ │ └── progress_screen.dart
│ ├── quiz/
│ │ └── quiz_screen.dart
│ ├── reminders/
│ │ └── reminders_screen.dart
│ ├── settings/
│ │ └── settings_screen.dart
│ ├── teacher_profile/
│ │ └── teacher_profile_screen.dart
│ ├── tips/
│ │ └── tips_screen.dart
│ ├── videos/
│ │ └── videos_screen.dart
│ └── wellbeing/
│ └── wellbeing_screen.dart
│
└── shared/widgets/
├── app_bottom_nav.dart // Persistent bottom navigation bar
├── app_card.dart // Themed card surface
├── audio_visualizer.dart // Animated waveform for music playback
├── feature_scaffold.dart // Scaffold wrapper with standard appbar
├── mini_audio_player.dart // Compact now-playing strip
├── module_card.dart // Card for a ModuleItem
├── section_header.dart // Section title + optional action
├── smart_bullet_list.dart // Renders newline-delimited strings as bullets
├── stat_card.dart // Metric display card (progress screen)
├── story_deck.dart // Swipeable card deck
├── timer_widget.dart // Countdown ring for exercise sessions
├── framer/
│ ├── framer_buttons.dart // Primary / secondary CTA buttons
│ └── spotlight_card.dart // Hero highlight card
└── media/
├── editorial_tip_card.dart // Rich tip display
├── exercise_session_layout.dart // Step + timer layout for exercises
├── flat_illustration.dart // Full-bleed illustration container
├── media_hero.dart // Large media header
├── media_thumbnail_card.dart // Video/audio thumbnail card
├── module_carousel.dart // Horizontal scrolling module list
├── mood_check_row.dart // Emotion mood selector row
└── step_pager.dart // Paginated step-through widget
Assets Structure
All static assets are declared in pubspec.yaml and resolved at build time. No network fetches occur at runtime:
assets/
├── audio/
│ ├── Sonido-del-bosque.mp3 // Forest ambient track
│ ├── Lluvia-Suave.mp3 // Soft rain track
│ └── Musica-energizante.mp3 // Energising music track
├── videos/
│ ├── Ergonomia_Postura_correcta.mp4 // Ergonomics posture video
│ └── 5_MINUTOS_DE_YOGA.mp4 // 5-minute yoga video
├── branding/
│ ├── logo.png
│ ├── logo-espoch.png
│ ├── logo-espoch-splash.png
│ ├── logo espoch-solo-splash.png
│ └── logo-esp.png
├── emotions/
│ ├── alegría_Inti.png // Joy character
│ ├── ansiedad_Chaskym.png // Anxiety character
│ ├── enojo_Rumirumi.png // Anger character
│ ├── miedo_Tutam.png // Fear character
│ └── tristeza_YAKU.png // Sadness character
├── illustrations/
│ └── splash_hero.png // App icon + splash hero
├── images/
│ ├── illustrations/ // Placeholder for future illustrations
│ └── thumbnails/ // Placeholder for future thumbnails
└── Extra/
├── ergonomia/
│ └── ergonomia_docente.png
└── posturas/
├── en_la_pizarra.png
├── usando_tablet.png
├── usando_computadora.png
├── usando_computadora_completo.png
├── de_pie.png
├── zonas_afectadas.png
├── de_pie_de_frente.png
├── de_pie_espaldas.png
├── de_pie_lado_derecho.png
└── de_pie_lado_izquierdo.png
Asset paths are centralised in AppAssets (lib/core/constants/app_assets.dart).
Always reference assets through that class rather than hard-coding path strings
in widgets.
Naming Conventions
| Subject | Convention | Example |
|---|
| Dart file names | snake_case | exercise_session_screen.dart |
| Class names | PascalCase | ExerciseSessionScreen |
| Feature screens | Class ends in Screen | TipsScreen, EmotionsScreen |
| State controllers | Class ends in Controller | LocaleController, AudioController |
| Scope / InheritedWidgets | Class ends in Scope | LocaleControllerScope |
| Constants classes | All members static const | AppConstants, AppAssets |
| Bilingual fields | Suffix Es / Qu | titleEs, titleQu |
| SharedPreferences keys | key prefix in AppConstants | AppConstants.keyLanguage |
Adding a New Feature
Follow these steps to introduce a new module into ErgoKawsay:
Create the screen file
Add lib/features/<name>/<name>_screen.dart and implement a StatelessWidget
or StatefulWidget named <Name>Screen.
Register a named route
Open lib/app.dart and add an entry to the routes map inside
_ErgoKawsayAppState.build():'/<name>': (_) => const <Name>Screen(),
Add a ModuleItem
Open lib/data/local/local_data_repository.dart and append a ModuleItem
to the modules getter, supplying a unique id, bilingual titles, an
icon, the route string, a color, and the appropriate HomeCategory.
Add i18n strings
Add all user-facing strings (in both Spanish and Kichwa) to
translations.yaml following the existing key naming pattern.
Regenerate tr.dart
Run the code-generation script from the project root to rebuild
lib/core/localization/tr.dart with the new keys:python tools/gen_translations.py
