# Virtual Mobile Monorepo

> **Note**: This README serves as comprehensive documentation for both human developers and AI development assistants like Claude Code. It contains setup instructions, development workflows, architecture details, and AI-specific guidelines.

This repository is a virtual monorepo that contains the Suno [Android](https://github.com/suno-ai/app-android) and [iOS](https://github.com/suno-ai/app-ios) apps, continuously synchronized as new commits are added to the source repositories.

## Repository Overview

This is a virtual mobile monorepo that contains Suno Android and iOS apps, continuously synchronized as subtrees from their respective source repositories:

- `android/` - Android app subtree (from suno-ai/app-android main branch)
- `ios/` - iOS app subtree (from suno-ai/app-ios develop branch)

The repository uses **git subtree** to pull new commits from source repositories and automatically creates PRs for local changes back to the source repos.

## Quick Start

### Setup
```bash
./INSTALL  # Install all dependencies (Ruby, bundler, pre-commit, etc.)
```

### Check Status
```bash
./fastlanew status                  # Check sync status of both platforms
```

### Sync with Upstream
```bash
./fastlanew sync                    # Sync both platforms with upstream repositories
```

### Commit Your Changes
```bash
git add .
git commit -m "feat: your changes"
```

### Next Sync Creates PRs
The next sync will automatically detect your local changes and create PRs back to the source repositories.

## Development Commands

### Setup
```bash
./INSTALL  # Install all dependencies (Ruby, bundler, pre-commit, etc.)
```

### Fastlane Usage
**Always use `./fastlanew` instead of `fastlane` directly** - this wrapper ensures correct version and environment.

#### Sync Commands
```bash
./fastlanew sync                    # Sync both platforms with upstream repositories
./fastlanew android sync            # Sync Android subtree only
./fastlanew ios sync               # Sync iOS subtree only
```

#### Status Commands (Read-Only)
```bash
./fastlanew status                  # Check sync status of both platforms
./fastlanew android status          # Check Android subtree sync status
./fastlanew ios status             # Check iOS subtree sync status
```

The `status` commands provide read-only information about:
- Current commit hash vs upstream commit hash
- Whether subtree exists or needs setup
- Recent local changes that would be pushed to upstream
- Required actions (sync needed, subtree setup, etc.)

#### Diff Commands
```bash
./fastlanew diff                    # Check which directories changed vs origin/main
./fastlanew diff base_ref:main      # Check changes against specific reference
```

### Android Development
```bash
cd android/
./gradlew check                  # Run all checks (lint, detekt, tests)
./gradlew detekt                 # Run static analysis
./gradlew ktlintCheck            # Check Kotlin code style
./gradlew ktlintFormat           # Format Kotlin code
./gradlew test                   # Run unit tests
./gradlew connectedAndroidTest   # Run instrumentation tests
./gradlew build                  # Build the app
```

### iOS Development
```bash
cd ios/
swift build                      # Build Swift package
swift test                       # Run tests
xcodebuild -workspace suno/suno.xcodeproj -scheme suno build  # Build iOS app
```

## Architecture

### Android Architecture (MVI + Hilt)
- **Dependency Injection**: Hilt across all modules
- **State Management**: MVI pattern with Kotlin Flow (StateFlow for UI state, SharedFlow for events)
- **Threading**: Coroutines with structured concurrency
- **UI**: Jetpack Compose with common-ui components
- **Data Flow**: UI (Compose) → ViewModel → Repository → [Network/Database]
- **Testing**: JUnit & MockK for unit tests, Compose testing for UI
- **Modules**: Modular architecture with common-* shared modules (common-ui, common-data, common-networking, etc.)

### iOS Architecture (TCA + SwiftUI)
- **State Management**: The Composable Architecture (TCA) pattern
- **UI**: SwiftUI with ComponentLibrary shared components
- **Dependencies**: Swift Package Manager with modular structure
- **Features**: Feature-based modules (FeatureApp, FeatureDiscover, FeatureProfile, etc.)
- **Clients**: Service layer with client abstractions (APIClient, PlayerClient, etc.)

## Automated Workflows

### Sync Workflow (`.github/workflows/sync.yml`)
Automated sync with upstream repositories:
1. Pulls latest changes from upstream repositories using git subtree (with `sync:` commit prefixes)
2. Fails if there are unstaged changes after sync
3. Pushes any unpushed commits to main branch (only when invoked on main branch)
4. Creates PRs for local changes back to source repositories
5. Skips execution if triggered by a `sync:` commit to avoid recursive syncing

### CI Workflows
**Main CI Workflow (`.github/workflows/ci.yml`)**
Orchestrates parallel CI jobs for pull requests:
1. **detect-changes**: Uses `fastlane diff` to detect which directories changed
2. **android-ci**: Calls `ci-android.yml` (only if android/ changed)
3. **ios-ci**: Calls `ci-ios.yml` (only if ios/ changed)
4. **root-ci**: Calls `ci-root.yml` (only if root files changed)
5. Skips execution if triggered by a `sync:` commit to avoid unnecessary CI runs

**Diff Detection Logic**
- **Pull requests**: Compares PR branch against base branch using `GITHUB_BASE_REF`
- **Push to main**: Compares current commit against previous commit (`HEAD~1`)
- **Local/other**: Defaults to comparing against `origin/main`
- Uses three-dot git diff syntax (`base...HEAD`) for accurate merge-base comparison

**Platform-Specific Workflows**
- **ci-android.yml**: Reusable Android CI (lint, detekt, tests, build)
- **ci-ios.yml**: Reusable iOS CI (Swift build, tests, Xcode build)
- **ci-root.yml**: Reusable root CI (fastlane validation, shellcheck, actionlint)

All platform workflows support `workflow_call` and `workflow_dispatch` triggers for standalone execution.

### Claude Code Integration

This repository uses the [Claude Code GitHub App](https://github.com/apps/claude-code) for AI-powered development assistance:

#### **Claude PR Assistant** ([claude.yml](.github/workflows/claude.yml))

- **Trigger**: Mention `@claude` in pull request comments, review comments, or issues
- **Features**: Interactive AI assistance for code review, debugging, and development questions
- **Usage**: Simply mention `@claude` followed by your question or request

#### **Claude Auto Review** ([claude-auto-review.yml](.github/workflows/claude-auto-review.yml))

- **Trigger**: Automatically runs on pull request creation and updates
- **Features**:
  - **PR Description Generation**: Automatically generates comprehensive descriptions for PRs with empty descriptions
  - **Automated Code Review**: Comprehensive review focusing on:
    - Code quality and best practices
    - Potential bugs or security issues
    - Performance considerations
    - Test coverage recommendations
    - Documentation updates
- **Output**: Updates PR descriptions and provides inline comments with constructive feedback

> Both workflows use the `ANTHROPIC_API_KEY` secret, which is tagged as _github-app-suno-mobile_ in [Claude Console](https://claude.ai/console).

## Code Conventions

### Fastlane Development
- **Always prefer standard Fastlane actions** over custom shell commands when available
- **Use `./fastlanew`** instead of `fastlane` directly - ensures correct Ruby/Fastlane versions
- **Create reusable actions** for common operations (see `fastlane/actions/`)
- **Use `sh()` helper** for shell commands instead of `Actions.sh` or backticks
- **Use standard helpers** like `ensure_git_status_clean`, `is_ci?`, etc.
- **Follow Fastlane naming conventions** for actions and parameters
- **Include comprehensive error handling** with meaningful user messages
- **Document all custom actions** with description, authors, return_value, and details

### Android
- Follow `.editorconfig` settings (4-space indent, UTF-8, LF line endings, max length 120)
- Use official `ktlint` style via pre-commit hook
- Run `detekt` for static analysis
- Place new screens under `app/src/main/java/com/suno/android/...`
- Name ViewModel classes with suffix `VM`
- Use Hilt for dependency injection

### iOS
- Swift Package Manager for dependencies
- SwiftUI + TCA pattern
- Feature-based modular architecture
- Use ComponentLibrary for shared UI components

## Important Files

- `fastlane/Fastfile` - Main sync orchestration logic with diff lane
- `fastlane/actions/sync_repo.rb` - Core sync implementation
- `fastlane/actions/check_diff.rb` - Single directory change detection
- `fastlane/actions/github_base_ref.rb` - GitHub environment-aware base reference detection
- `fastlane/actions/github_output.rb` - GitHub Actions output integration
- `.github/workflows/sync.yml` - Automated sync workflow
- `.github/workflows/ci.yml` - Main CI orchestration workflow
- `.github/workflows/ci-android.yml` - Reusable Android CI workflow
- `.github/workflows/ci-ios.yml` - Reusable iOS CI workflow
- `.github/workflows/ci-root.yml` - Reusable root CI workflow
- `.github/workflows/claude.yml` - Claude PR Assistant (interactive AI help)
- `.github/workflows/claude-auto-review.yml` - Automated PR reviews
- `android/.cursorrules` - Android-specific AI coding guidelines
- `android/docs/architecture.generated.md` - Detailed Android architecture

## AI Development Guidelines

This section provides specific guidance for AI development assistants working with this codebase.

### Vibe Coding Guidelines

- Do what has been asked; nothing more, nothing less
- NEVER create files unless they're absolutely necessary for achieving your goal
- ALWAYS prefer editing an existing file to creating a new one
- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User
- Follow the existing code style and patterns in each platform
- Use the established dependency injection patterns (Hilt for Android, TCA for iOS)
- Maintain the modular architecture approach

### AI Agents Guidelines (Claude Code, Cursor, Windsurf)

#### Development Approach
- **Always prefer fastlane lanes and actions over shell scripts**
- Create reusable lanes for common development tasks
- Use fastlane's built-in actions and UI methods for better user experience
- Extract complex logic into separate lanes rather than inline shell commands

#### Mobile Development
- Do not modify code in `android/` or `ios/` directories unless explicitly asked
- Use `./fastlanew` wrapper to invoke fastlane commands
- Focus on monorepo management and automation tasks

#### Git Subtree Management
- Use git subtree for bidirectional sync with upstream repositories
- Android maps to `main` branch, iOS maps to `develop` branch
- Maintain clean separation between monorepo tooling and app code

#### Automation Preferences
- Create fastlane lanes for GitHub Actions logic to enable local testing
- Use descriptive lane names and documentation
- Provide both automated and manual workflow options

#### Code Style Requirements
- Follow `.editorconfig` settings for consistency
- Use pre-commit hooks for code formatting
- Run platform-specific linting tools before committing
- NEVER add comments unless explicitly requested
- Follow security best practices, never expose secrets or keys