Development Guidelines & PRs
Relevant source files
The following files were used as context for generating this wiki page:
MoodTune follows a structured development workflow based on Clean Architecture and strict coding standards to ensure code quality and maintainability across its Flutter mobile application and FastAPI backend. These guidelines govern how code is written, tested, and integrated through the Pull Request (PR) process.
The scope of these guidelines includes architectural patterns like the Presentation-Domain-Data layer separation, state management using BLoC, and CI/CD procedures for deployment. For implementation details on specific systems, see the Authentication System and Routing System documentation.
Sources: CLAUDE.md:46-48, README.md:52-60
Architectural Standards
The project implements Clean Architecture with a strict unidirectional dependency flow where dependencies always point inward: Presentation → Domain ← Data. Each feature is encapsulated within its own directory following this three-layer structure.
Layer Definitions
| Layer | Responsibility | Key Components |
|---|---|---|
| Presentation | UI Logic and State Management | BLoCs, Views, Reusable Widgets |
| Domain | Business Logic and Contracts | Entities (Equatable), Repository Interfaces, Use Cases |
| Data | External Infrastructure | Datasources (Dio/Supabase), Models (JSON serialization), Repositories |
Sources: CLAUDE.md:46-64
Dependency Flow Diagram
The following diagram illustrates how components interact across layers while maintaining isolation.
This structure ensures that the Domain layer remains pure Dart code without framework dependencies, facilitating easier testing and maintenance.
Sources: CLAUDE.md:46-64, authplan.md:20-40
Coding & Development Rules
State Management & Error Handling
The application uses the BLoC (Business Logic Component) pattern for state management. BLoCs utilize a single state class with a copyWith method and an enum-based status field. Error handling is standardized using the ResultFuture<T> pattern, which utilizes the Either type from the dartz package.
// Standardized Result Type
typedef ResultFuture<T> = Future<Either<Failure, T>>;
// Implementation in BLoC
final result = await _repository.operation();
result.fold(
(failure) => emit(state.copyWith(status: Status.error, error: failure.message)),
(data) => emit(state.copyWith(status: Status.success, data: data)),
);
Sources: CLAUDE.md:79-99, utils/typedef.dart
Command Reference
Developers must use the following commands for routine tasks to ensure environment consistency:
- Running App: Always use
--dart-define-from-file.- Development:
flutter run --flavor development --target lib/main_development.dart --dart-define-from-file=dev.env - Production:
flutter run --flavor production --target lib/main_production.dart --dart-define-from-file=.env
- Development:
- Testing:
very_good test --coverage --test-randomize-ordering-seed random - Formatting:
dart format .andflutter analyze - Code Generation:
flutter packages pub run build_runner build --delete-conflicting-outputs
Sources: CLAUDE.md:12-44, README.md:65-75
Pull Request Guidelines
To maintain code quality, all Pull Requests must adhere to the standardized template. This ensures that every change is documented, tested, and aligned with project goals.
PR Requirements Checklist
Contributors must verify the following before submission:
- Testing: Unit tests must be written for new logic, and all existing tests must pass.
- Documentation: README or relevant
/docsfiles must be updated. - Standards: Code must pass
flutter analyzeand follow thevery_good_analysislinting rules. - Self-Review: The author must perform a self-review of the code.
Sources: .github/PULL_REQUEST_TEMPLATE.md:20-45, README.md:16-20
PR Lifecycle Sequence
The sequence below describes the path of a code change from local development to the master branch.
Deployment to iOS TestFlight is automatically handled by Codemagic upon merging into the production branch, provided the BUILD_NUMBER is incremented.
Sources: codemagic.yaml:1-60, .github/PULL_REQUEST_TEMPLATE.md:1-15
CI/CD and Deployment
The project uses Codemagic for continuous integration and delivery, specifically targeting iOS TestFlight distributions.
Build Configuration Variables
These variables must be defined in the Codemagic environment groups:
| Group | Required Variables |
|---|---|
| Supabase | SUPABASE_URL, SUPABASE_ANON_KEY |
| Sentry | SENTRY_DSN |
| MoodTune | API_BASE_URL, JAMENDO_CLIENT_ID |
Sources: codemagic.yaml:15-25, README.md:85-95
The deployment script automatically determines the build number by querying App Store Connect and fetching the version from pubspec.yaml before running flutter build ipa.
Sources: codemagic.yaml:40-55
Summary
Development in the MoodTune repository is governed by Clean Architecture principles, ensuring a clear separation between business logic and infrastructure. By adhering to the standardized BLoC patterns, ResultFuture error handling, and the comprehensive PR checklist, developers contribute to a stable and scalable codebase. Automated pipelines via Codemagic ensure that every merged contribution is tested and ready for staging or production deployment.