Skip to content

GEMINI.md

Latest commit

 

History

History
93 lines (66 loc) · 3.4 KB

GEMINI.md

File metadata and controls

93 lines (66 loc) · 3.4 KB

Musly Project: Gemini Agent Instructions

This document provides a comprehensive guide for the Gemini agent to understand, build, and contribute to the Musly project.

Project Overview

Musly is a cross-platform music streaming client for Subsonic and Navidrome servers. The main application is built with Flutter and Dart, targeting Android, iOS, Windows, Linux, and macOS. It features an Apple Music-inspired interface, offline playback, Android Auto support, and smart recommendations.

The project also includes a companion website built with React and Vite, located in the react-website directory. This website is automatically deployed to GitHub Pages via a GitHub Actions workflow.

Core Technologies

  • Flutter Application:

    • Language: Dart
    • Framework: Flutter
    • State Management: Provider
    • Audio Playback: just_audio
    • HTTP Client: dio
    • Dependencies: See pubspec.yaml for a full list.

  • React Website:

    • Framework: React
    • Build Tool: Vite
    • Dependencies: See react-website/package.json

Building and Running the Project

Flutter Application

  1. Install Dependencies:

    flutter pub get

  2. Run the App:

    flutter run

    You can specify a target device with the -d flag (e.g., flutter run -d chrome).

React Website

  1. Navigate to the website directory:

    cd react-website

  2. Install Dependencies:

    npm install

  3. Run in Development Mode:

    npm run dev

  4. Build for Production:

    npm run build

Development Conventions

Code Style and Linting

  • Dart/Flutter: The project follows the standard linting rules provided by the flutter_lints package, as configured in analysis_options.yaml. Please adhere to these conventions.
  • React/JS: The React website uses ESLint for code quality, configured in eslint.config.js.

State Management

The Flutter app uses the provider package for state management. Key providers are initialized in lib/main.dart and can be found in the lib/providers/ directory. When adding new state, prefer using the Provider pattern.

Project Structure

  • lib/: Contains all the Dart source code for the Flutter application.
    • main.dart: The entry point of the application.
    • models/: Data models for the application (e.g., Song, Album).
    • providers/: State management classes (e.g., PlayerProvider, AuthProvider).
    • screens/: UI for different screens of the app.
    • services/: Business logic and services (e.g., interacting with the Subsonic API, offline storage).
    • widgets/: Reusable UI components.
  • react-website/: Contains the source code for the companion website.
  • .github/workflows/: Contains CI/CD configurations. deploy-website.yml handles the deployment of the React website.
  • test/: Contains tests for the Flutter application.

API Interaction

The primary service for interacting with the Subsonic API is SubsonicService located in lib/services/subsonic_service.dart. All API calls should be centralized through this or similar services.

Testing

Tests are located in the test/ directory. When adding new features or fixing bugs, please add corresponding tests. Run tests using the flutter test command.