Getting Started & Local Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• pubspec.yaml
• authplan.md
• routing_plan.md
• codemagic.yaml

MoodTune is a Flutter-based mobile application designed for song and playlist mood analysis. It leverages a FastAPI backend powered by Python and librosa for audio processing, while utilizing Supabase for authentication and data persistence. This guide details the environment configuration, dependency management, and execution procedures required to set up the project locally for development, staging, or production.

The application architecture follows Clean Architecture principles, separating concerns into Presentation, Domain, and Data layers. This structure ensures that business logic remains independent of the UI framework or external data sources, facilitating easier testing and local development.
Sources: README.md:1-5, CLAUDE.md:6-12, CLAUDE.md:46-52

Environment Configuration

MoodTune relies on environment variables for sensitive credentials and service endpoints. These are injected into the Flutter application using the --dart-define-from-file flag during the build or run process.

Required Variables

The project uses specific configuration keys for Supabase integration, backend API communication, and monitoring.

Variable	Description	Default / Example
SUPABASE_URL	The URL for your Supabase project instance	https://xyz.supabase.co
SUPABASE_ANON_KEY	The anonymous public key for Supabase	(Project specific)
API_BASE_URL	The base URL for the FastAPI backend service	http://127.0.0.1:8000/api/v1
SENTRY_DSN	(Optional) DSN for Sentry error monitoring	(Optional)

Sources: README.md:64-74, CLAUDE.md:131-140

Local Setup Steps

To prepare the environment for local execution:

1. Create a local environment file by copying the template: cp env.example .env.
2. For development-specific keys, maintain a dev.env file.
3. Ensure the API_BASE_URL points to your locally running FastAPI backend if not using the production URL.

Sources: README.md:60-62, CLAUDE.md:15-18

Project Execution & Flavors

The project is structured around three distinct flavors: Development, Staging, and Production. Each flavor targets a specific main entry point and utilizes different environment files.

The diagram shows the command structure for launching the application in different environments using Flutter's flavor system.
Sources: README.md:52-58, CLAUDE.md:20-25

Local Development Workflow

Dependency Management

Dependencies are managed via pubspec.yaml. Before running the app, install all packages and generate necessary code (for BLoC, JSON serialization, etc.).

# Fetch dependencies
flutter pub get

# One-shot code generation
flutter packages pub run build_runner build --delete-conflicting-outputs

# Localization generation
flutter gen-l10n --arb-dir="lib/l10n/arb"

Sources: CLAUDE.md:38-40, CLAUDE.md:42-44, pubspec.yaml:1-35

Testing and Quality Assurance

MoodTune uses the very_good CLI for testing and coverage reporting. Tests should be run with a randomized seed to ensure robustness.

# Run all tests with coverage
very_good test --coverage --test-randomize-ordering-seed random

# Run specific test file
flutter test test/path/to/test.dart

Sources: README.md:78-80, CLAUDE.md:28-32

System Architecture Overview

The local setup supports a Clean Architecture flow where data sources interact with the FastAPI backend and Supabase.

The sequence diagram illustrates the request-response cycle from the user interface through the internal architectural layers to the external backend API.
Sources: CLAUDE.md:56-78, CLAUDE.md:144-149

CI/CD and Build Automation

Builds for staging and production are automated via Codemagic. The configuration includes environment groups for Supabase and Sentry, and scripts for build number determination based on the current pubspec.yaml version.

Codemagic Configuration Keys

• iOS Signing: Uses com.jmagic.moodtune as the bundle identifier.
• Environment Groups: Supabase, Sentry, and MoodTune.
• Build Artifacts: IPAs are generated using flutter build ipa --release --flavor production.

Sources: codemagic.yaml:1-55, pubspec.yaml:5-6

Summary

Setting up MoodTune locally requires configuring environment variables for Supabase and the FastAPI backend, installing Flutter dependencies, and running the application using flavor-specific commands. The project's adherence to Clean Architecture and the use of the ResultFuture pattern for error handling ensures a predictable development environment. By following the flavor targets and using the provided environment file templates, developers can seamlessly switch between local testing and production-like staging environments.