App Flavors & Environments
Relevant source files
The following files were used as context for generating this wiki page:
MoodTune utilizes a multi-flavor architecture to segregate development, staging, and production environments. This ensures that sensitive credentials, API endpoints, and third-party integrations (like Supabase and Sentry) remain isolated across different stages of the software development lifecycle.
The environment configuration is primarily managed through Dart defines and environment files (.env, dev.env), which are injected during the build process to provide runtime constants to the Flutter application.
Flavor Architecture
The application supports three distinct flavors, each mapped to a specific entry point in the lib/ directory. This allows for environment-specific initialization logic, such as configuring different logging levels or analytics keys.
The diagram shows the relationship between build flavors and the corresponding Dart entry points.
Sources: README.md:57-67, CLAUDE.md:14-20
Available Flavors
| Flavor | Target File | Purpose |
|---|---|---|
development | lib/main_development.dart | Local development and testing with dev.env |
staging | lib/main_staging.dart | Pre-production validation and QA |
production | lib/main_production.dart | Final release build for end-users |
Sources: README.md:57-67, CLAUDE.md:14-20
Environment Configuration
Configuration values are managed through .env files and injected using the --dart-define-from-file flag. This method ensures that secrets like Supabase keys and API URLs are not hardcoded into the source.
Essential Variables
| Variable | Description | Example / Usage |
|---|---|---|
SUPABASE_URL | Supabase project URL | Auth and Database connectivity |
SUPABASE_ANON_KEY | Supabase anonymous key | Client-side data access |
API_BASE_URL | FastAPI backend base URL | Mood analysis and history endpoints |
SENTRY_DSN | Sentry monitoring DSN | Optional; error tracking and reporting |
JAMENDO_CLIENT_ID | Jamendo API client ID | Music catalog browsing |
Sources: README.md:73-82, CLAUDE.md:104-110, codemagic.yaml:49-55
Local Execution Commands
For local development, the development flavor is typically paired with dev.env.
# Run Development Flavor
flutter run --flavor development \
--target lib/main_development.dart \
--dart-define-from-file=dev.env
# Run Production Flavor locally
flutter run --flavor production \
--target lib/main_production.dart \
--dart-define-from-file=.env
Sources: README.md:84-88, CLAUDE.md:14-20
Continuous Integration & Deployment (CI/CD)
The project uses Codemagic for automated builds, specifically targeting the production flavor for iOS TestFlight distribution.
Workflow Integration
The CI environment manages variables through secret groups (Supabase, Sentry, MoodTune). During the build process, Codemagic injects these secrets into the flutter build ipa command using individual --dart-define flags.
The sequence diagram illustrates how secrets are retrieved and injected during the CI build process.
Sources: codemagic.yaml:15-25, codemagic.yaml:47-57
Build System Configuration
Windows Configuration
The Windows build system (CMake) is configured to handle different build modes: Debug, Profile, and Release. These correlate with the Flutter build modes rather than the application flavors.
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Flutter build mode" FORCE)
set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Profile" "Release")
endif()
Sources: windows/CMakeLists.txt:14-23
Android Configuration
The AndroidManifest.xml uses placeholders like ${appName} and ${applicationName}, allowing the Flutter build tool to inject flavor-specific values (such as different application labels for Dev vs. Prod).
Sources: android/app/src/main/AndroidManifest.xml:3-5
Summary
The MoodTune environment strategy relies on Flutter flavors to separate execution targets and Dart defines to manage configuration state. By using main_development.dart, main_staging.dart, and main_production.dart entry points, the architecture facilitates a clean separation of concerns, ensuring that development traffic and logs do not interfere with production systems while maintaining a unified codebase.