# SwingMusic Extended - Unified CI/CD System

## Overview

This repository uses a unified CI/CD system that builds all components from the main repository. The main repository (`swingmusic-extended`) contains submodules for each component:

- **Backend**: Python server (in `src/`)
- **Web Client**: Vue.js frontend (submodule `swingmusic-webclient`)
- **Desktop App**: Tauri desktop app (submodule `swingmusic-desktop`) 
- **Android App**: Android app (submodule `swingmusic-android`)

## Workflows

### 1. Unified Build (`unified-build.yml`)

This is the main workflow that builds all components. It runs on:
- Push to any branch
- Pull requests from any branch
- Tags (for releases)
- Manual dispatch

**Features:**
- **Smart change detection**: Only builds components that changed
- **Parallel builds**: All components build simultaneously when possible
- **Cross-platform builds**: Desktop app builds for Linux, Windows, and macOS
- **Docker integration**: Creates Docker image with backend + web client
- **Release automation**: Automatic releases on tags

**Build Process:**
1. Initializes and updates all submodules
2. Detects which components changed
3. Builds only what's needed (or everything on main/tags)
4. Creates artifacts for each component
5. Builds Docker image with backend + web client
6. Creates GitHub release (on tags)

### 2. Component Tests (`component-tests.yml`)

Lightweight testing workflow for development. Runs on:
- Push to develop branch
- Pull requests
- Manual dispatch

**Purpose:**
- Quick feedback during development
- Tests individual components without full builds
- Runs linting, unit tests, and basic build checks

### 3. Desktop CI (`desktop-ci.yml`)

Legacy desktop-specific workflow (kept for compatibility).

## Usage

### Automatic Builds

- **Development**: Push to `develop` → Component tests run
- **Main branch**: Push to `main`/`master` → Full unified build
- **Release**: Create tag `v*` → Full build + release

### Manual Builds

You can trigger builds manually with parameters:

1. Go to Actions → Unified Build → "Run workflow"
2. Choose components to build (comma-separated):
   - `webclient,desktop,android,backend` (default: all)
   - `webclient,backend` (just web and backend)
   - `desktop` (just desktop app)

### Smart Change Detection

The unified workflow automatically detects changes:
- Files in `swingmusic-webclient/` → Builds web client
- Files in `swingmusic-desktop/` → Builds desktop app
- Files in `swingmusic-android/` → Builds Android app
- Files in `src/` → Builds backend
- No changes → Skips unchanged components (except on main/tags)

## Artifacts and Releases

### Build Artifacts

Each component produces artifacts:
- **Web Client**: Built frontend files
- **Desktop Apps**: Platform-specific installers
- **Android App**: APK files
- **Backend**: Python wheels

### Docker Images

Built images are pushed to GitHub Container Registry:
- `ghcr.io/Dvorinka/swingmusic-extended:main-123`
- `ghcr.io/Dvorinka/swingmusic-extended:latest`
- `ghcr.io/Dvorinka/swingmusic-extended:v1.0.0`

### Releases

On tags, automatic releases include:
- Docker image information
- Download links for all components
- Installation instructions
- Auto-generated changelog

## Repository Structure

```
swingmusic-extended/
├── .github/workflows/          # CI/CD workflows
├── src/                        # Backend Python code
├── swingmusic-webclient/       # Submodule: Web frontend
├── swingmusic-desktop/         # Submodule: Desktop app
├── swingmusic-android/         # Submodule: Android app
├── Dockerfile                  # Docker configuration
└── .gitmodules                 # Submodule configuration
```

## Development Workflow

### Making Changes

1. **Backend changes**: Edit files in `src/`
2. **Web client changes**: 
   - Navigate to `swingmusic-webclient/`
   - Make changes
   - Commit and push in that submodule
   - Update submodule reference in main repo
3. **Desktop changes**: Same process in `swingmusic-desktop/`
4. **Android changes**: Same process in `swingmusic-android/`

### Updating Submodules

After making changes in a submodule:

```bash
# In the submodule directory
cd swingmusic-webclient
git add .
git commit -m "Update web client"
git push

# Back in main repository
cd ..
git add swingmusic-webclient
git commit -m "Update webclient submodule"
git push
```

### Testing Changes

- **Small changes**: Push to `develop` for quick component tests
- **Full integration**: Push to `main` for complete build
- **Release**: Create tag for production release

## Troubleshooting

### Submodule Issues

If builds fail due to submodule issues:

```bash
git submodule update --init --recursive
git submodule sync --recursive
```

### Build Failures

Check the Actions tab for detailed logs. Common issues:
- Missing dependencies in submodules
- Outdated submodule references
- Build tool version mismatches

### Manual Intervention

You can always:
- Run workflows manually with specific components
- Re-run failed jobs
- Download and test artifacts manually