AeThex-OS/LAUNCHER_QUICKSTART.md

# AeThex Desktop Launcher - Quick Start Guide

## 🎯 What Has Been Built

A complete desktop application launcher similar to Battle.net and Epic Games Launcher, featuring:

✅ **Modern UI**
- Battle.net/Epic-style interface with grid/list views
- Tab-based navigation (Library, Store, Updates, Downloads)
- Progress tracking for installations
- Play time and last played stats

✅ **Desktop Integration**
- System tray support (minimize to tray)
- Native window controls
- Auto-updater integration
- Cross-platform (Windows, macOS, Linux)

✅ **App Management**
- Launch apps from library
- Install/uninstall apps
- Track download progress
- Check for updates

✅ **Build System**
- Automated build scripts for all platforms
- GitHub Actions CI/CD workflow
- Platform-specific installers (MSI, DMG, DEB, AppImage)

## 🚀 Quick Start

### For Development

```bash
# Install dependencies
npm install

# Run in development mode (opens launcher UI)
npm run dev:launcher
```

This will start the Tauri dev server with hot-reload enabled.

### For Production Build

```bash
# Build for your current platform
npm run build:launcher

# Or use the build script
./build-launcher.sh        # Linux/macOS
.\build-launcher.ps1       # Windows PowerShell
```

### Platform-Specific Builds

```bash
# Windows
npm run build:launcher:windows

# macOS (requires macOS to build)
npm run build:launcher:macos

# Linux
npm run build:launcher:linux
```

## 📁 What Was Created

### New Files

1. **UI Components**
   - `client/src/components/DesktopLauncher.tsx` - Main launcher UI component
   - `client/src/pages/launcher.tsx` - Launcher page

2. **Backend/Tauri**
   - `src-tauri/src/lib.rs` - Enhanced with launcher commands
   - `src-tauri/Cargo.toml` - Updated with new dependencies
   - `src-tauri/tauri.conf.json` - Updated with launcher config

3. **Build System**
   - `build-launcher.sh` - Unix/Linux build script
   - `build-launcher.ps1` - Windows PowerShell build script
   - `.github/workflows/build-launcher.yml` - CI/CD workflow

4. **Documentation**
   - `LAUNCHER_README.md` - Complete launcher documentation
   - `LAUNCHER_BUILD.md` - Detailed build instructions
   - `LAUNCHER_QUICKSTART.md` - This file

### Modified Files

1. **Routing**
   - `client/src/App.tsx` - Added `/launcher` route

2. **Package Scripts**
   - `package.json` - Added launcher build scripts

## 🎨 Features Overview

### Library Tab
- See all installed applications
- Launch button for quick access
- Switch between grid and list views
- View play time and last played date

### Store Tab
- Browse available applications
- Install new apps with one click
- Featured apps section

### Updates Tab
- Check for app updates
- View update history
- One-click update all

### Downloads Tab
- Track active downloads
- See installation progress
- Manage download queue

## 🔧 How It Works

### Architecture

```
┌─────────────────────────────────────┐
│   React UI (DesktopLauncher.tsx)   │
│  - Library, Store, Updates, etc.    │
└──────────────┬──────────────────────┘
               │
               │ Tauri IPC
               │
┌──────────────▼──────────────────────┐
│     Rust Backend (lib.rs)           │
│  - launch_app()                     │
│  - install_app()                    │
│  - uninstall_app()                  │
│  - check_for_updates()              │
└──────────────┬──────────────────────┘
               │
               ▼
         Native OS APIs
```

### Tauri Commands

The Rust backend exposes these commands to the frontend:

- **`launch_app(app_id)`** - Opens an application in a new window
- **`install_app(app_id)`** - Downloads and installs an app
- **`uninstall_app(app_id)`** - Removes an installed app
- **`check_for_updates()`** - Checks for available updates
- **`get_installed_apps()`** - Returns list of installed apps
- **`open_app_folder(app_id)`** - Opens app folder in file explorer

### System Tray

The launcher minimizes to system tray with:
- Left click: Show/hide window
- Right click: Context menu (Show, Quit)
- Auto-start on login (configurable)

## 🎯 Next Steps

### 1. Test the Launcher

```bash
# Start in dev mode
npm run dev:launcher
```

Navigate to the launcher (`/launcher` route) and test:
- ✅ Switching between tabs
- ✅ Changing view modes (grid/list)
- ✅ Try installing/launching apps (mock functionality)

### 2. Customize Branding

Update these files with your branding:
- `src-tauri/icons/` - Replace with your app icons
- `src-tauri/tauri.conf.json` - Update app name, publisher
- `client/src/components/DesktopLauncher.tsx` - Customize colors

### 3. Add Real Apps

Modify the `apps` array in `DesktopLauncher.tsx` to add your actual applications:

```typescript
const [apps, setApps] = useState<LauncherApp[]>([
  {
    id: 'your-app',
    name: 'Your App Name',
    description: 'App description',
    version: '1.0.0',
    size: '100 MB',
    installed: false,
    installing: false,
    image: '/your-app-image.jpg'
  }
]);
```

### 4. Implement Real Download Logic

The current implementation simulates downloads. For real downloads:

1. Add a download service in Rust backend
2. Use `tauri-plugin-http` for network requests
3. Stream download progress to frontend
4. Extract/install downloaded files

### 5. Setup Auto-Updates

1. Generate signing keys:
   ```bash
   npm run tauri signer generate
   ```

2. Configure update endpoint in `tauri.conf.json`

3. Setup update server (see Tauri docs)

### 6. Build for Distribution

```bash
# Build production version
npm run build:launcher

# Find installers in:
# - Windows: src-tauri/target/release/bundle/msi/
# - macOS:   src-tauri/target/release/bundle/dmg/
# - Linux:   src-tauri/target/release/bundle/appimage/
```

### 7. Setup CI/CD

The GitHub Actions workflow is ready at `.github/workflows/build-launcher.yml`.

Add these secrets to your GitHub repository:
- `TAURI_SIGNING_PRIVATE_KEY`
- `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`

For macOS builds, also add:
- `APPLE_CERTIFICATE`
- `APPLE_CERTIFICATE_PASSWORD`
- `APPLE_ID`
- `APPLE_PASSWORD`
- `APPLE_TEAM_ID`

## 📚 Resources

- **Launcher UI**: [client/src/components/DesktopLauncher.tsx](client/src/components/DesktopLauncher.tsx)
- **Rust Backend**: [src-tauri/src/lib.rs](src-tauri/src/lib.rs)
- **Full Docs**: [LAUNCHER_README.md](LAUNCHER_README.md)
- **Build Guide**: [LAUNCHER_BUILD.md](LAUNCHER_BUILD.md)
- **Tauri Docs**: https://v2.tauri.app/

## 🐛 Troubleshooting

### "Command not found: tauri"

Install Tauri CLI:
```bash
npm install @tauri-apps/cli@latest --save-dev
```

### Build fails on Linux

Install dependencies:
```bash
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libayatana-appindicator3-dev librsvg2-dev
```

### Can't see system tray icon

On Linux, ensure your desktop environment supports system tray icons.

### Dev mode shows blank screen

Check that:
1. Vite dev server is running
2. Port 5000 is available
3. No firewall blocking localhost

## 💡 Tips

1. **Custom Icons**: Replace icons in `src-tauri/icons/` with your branding
2. **Theme**: The UI uses your shadcn/ui theme configuration
3. **Plugins**: Add more Tauri plugins as needed (filesystem, shell, etc.)
4. **Analytics**: Track app usage with your analytics service
5. **Localization**: Add i18n for multiple languages

## 🎉 You're Ready!

Your desktop launcher is complete and ready for:
- ✅ Development testing
- ✅ Customization
- ✅ Adding real apps
- ✅ Building for distribution
- ✅ Setting up auto-updates
- ✅ CI/CD automation

**Happy launching! 🚀**

---

For issues or questions, see the full documentation in `LAUNCHER_README.md` and `LAUNCHER_BUILD.md`.