Melos Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page:
The BT Speaker project is organized as a Flutter-embedded monorepo managed by Melos 7.x. This structure facilitates the simultaneous development of a Raspberry Pi display application, a mobile companion application, and shared core logic. By utilizing Melos, the project maintains consistent analysis, formatting, and testing workflows across all sub-projects while allowing for modular dependency management.
The repository follows the modern Dart/Flutter workspace resolution, ensuring that local package dependencies are resolved correctly within the monorepo environment. This is critical for the bt_speaker_core package, which provides shared models and logic used by both executable applications.
Sources: CLAUDE.md:12-16, pubspec.yaml:7-10, README.md:19-25
Workspace Architecture
The monorepo is divided into two primary directories: apps/ for executable targets and packages/ for shared libraries. The root configuration utilizes Flutter's workspace feature, which is required by Melos 7.x for modern package resolution.
Component Breakdown
| Directory | Package Name | Description |
|---|---|---|
apps/pi_app | pi_app | Flutter app running on Raspberry Pi via flutter-pi. |
apps/phone_app | bt_speaker | Flutter companion app for iOS/Android. |
packages/bt_speaker_core | bt_speaker_core | Shared data models (BeatData, NowPlaying, EqSettings, LedCommand). |
Sources: CLAUDE.md:12-16, pubspec.yaml:7-10, README.md:21-25
Dependency Graph
The following diagram illustrates the relationship between the shared core package and the platform-specific applications.
The pi_app and phone_app both depend on bt_speaker_core via relative path references in their respective pubspec.yaml files.
Sources: apps/phone_app/pubspec.yaml:45-46, apps/pi_app/pubspec.yaml:38-39
Melos Configuration and Scripts
The melos.yaml file defines the monorepo's operational commands. It is configured to target packages based on specific filters, such as whether a directory contains tests or if files have changed relative to the main branch.
Automated Workflows
Melos enables several lifecycle scripts that ensure code quality across the repository:
- analyze: Runs
flutter analyzeon changed packages to detect issues early. - format: Validates Dart formatting for changed files.
- test: Executes
flutter testwith coverage reporting, specifically filtering for packages that contain atest/directory. - lint: A composite command that runs both analysis and formatting checks.
melos:
scripts:
analyze:
description: Run flutter analyze on changed packages only.
run: melos exec --concurrency=1 -- flutter analyze --fatal-infos
packageFilters:
diff: origin/main
test:
description: Run tests on changed packages that have a test directory.
run: melos exec --concurrency=1 -- flutter test --coverage --test-randomize-ordering-seed=random
packageFilters:
dirExists: test
diff: origin/main
Sources: melos.yaml:3-33, pubspec.yaml:16-44
Package Resolution and SDK
The project uses a unified SDK path and workspace resolution strategy to avoid version conflicts between the Pi and Mobile environments.
- SDK Path: The workspace is configured to use the SDK found at
.fvm/flutter_sdk. - Resolution: Each package uses
resolution: workspaceto ensure they participate in the shared dependency resolution mechanism of the root project. - FVM Support: The configuration points to a specific Flutter version (3.41.9 stable as per Claude Guide) managed via Flutter Version Management (FVM).
Sources: melos.yaml:34, CLAUDE.md:25, apps/phone_app/pubspec.yaml:6, packages/bt_speaker_core/pubspec.yaml:5
CI Integration
The monorepo structure is designed for a GitHub Actions matrix. The CI pipeline leverages Melos scripts to run tests across all three packages. A specific guard if [ -d "test" ] is recommended in CI configurations because not all packages (specifically phone_app in early phases) contain a test directory.
Sources: CLAUDE.md:73-75, melos.yaml:15-20
The Melos monorepo structure provides a scalable foundation for the BT Speaker project, ensuring that the Pi-specific embedded code and the Mobile companion code remain synchronized through the shared bt_speaker_core package while maintaining high standards through automated scripts.