# StarCitizenToolBox Flutter/Rust Desktop Application

StarCitizenToolBox is a Flutter desktop application with Rust native bindings designed for Star Citizen players. It provides localization management, game diagnostics, website translations, performance optimization, and various tools for the Star Citizen gaming experience. The app supports Windows, macOS, and Linux platforms using Fluent UI design.

Always reference these instructions first and fallback to additional search or context gathering only when information in these instructions is incomplete or found to be in error.

## Working Effectively

### Initial Setup and Dependencies

Install required dependencies in this exact order:

1. **Install Rust toolchain:**
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
   source ~/.cargo/env
   ```

2. **Install Flutter SDK (stable channel):**
   ```bash
   # Clone Flutter repository
   cd /tmp
   git clone https://github.com/flutter/flutter.git -b stable --depth 1
   export PATH="/tmp/flutter/bin:$PATH"
   flutter --version
   ```
   Note: If Flutter download fails due to network issues, the build can still proceed with existing generated code.

3. **Install essential Rust tools:**
   ```bash
   cargo install cargo-expand
   cargo install 'flutter_rust_bridge_codegen@^2.0.0-dev.0'
   ```

### Build Process - NEVER CANCEL LONG-RUNNING COMMANDS

Execute these commands in sequence. **NEVER CANCEL** - builds can take 45+ minutes:

1. **Install Flutter dependencies:** (2-3 minutes)
   ```bash
   flutter pub get
   ```

2. **Generate Dart code:** (3-5 minutes)
   ```bash
   dart run build_runner build --delete-conflicting-outputs
   ```

3. **Update Rust dependencies:** (10-15 minutes first time, 2-3 minutes subsequent)
   ```bash
   cd rust && cargo update
   ```

4. **Generate Rust-Dart bridge code:** (5-8 minutes)
   ```bash
   flutter_rust_bridge_codegen generate
   ```

5. **Generate localization files:** (1-2 minutes)
   ```bash
   flutter pub global activate intl_utils
   flutter pub global run intl_utils:generate
   ```

6. **Build Rust components:** (60-90 seconds debug, 110-120 seconds release)
   ```bash
   cd rust
   cargo build --release  # NEVER CANCEL: Takes ~2 minutes
   ```

7. **Build Flutter application:** (15-25 minutes - NEVER CANCEL)
   ```bash
   flutter build windows -v  # Set timeout to 30+ minutes minimum
   ```

**CRITICAL BUILD TIMING:**
- Complete full build from scratch: **45-60 minutes** - NEVER CANCEL
- Rust release build: **2 minutes** - NEVER CANCEL  
- Flutter application build: **15-25 minutes** - NEVER CANCEL
- Code generation steps: **10-15 minutes total** - NEVER CANCEL

### Platform-Specific Build Requirements

**Windows (Primary Platform):**
- MSBuild tools
- Visual Studio Build Tools or Visual Studio Community
- Windows SDK
- LLVM/Clang (version 18+ recommended)

**Linux (Development/Testing):**
- Basic build tools: `build-essential`, `cmake`, `ninja-build`
- GTK development libraries
- Limited functionality (desktop app designed primarily for Windows)

**macOS:**
- Xcode Command Line Tools
- CMake

### Testing and Validation

**Rust Component Testing:**
```bash
cd rust
cargo check  # Fast syntax check (1-2 minutes)
cargo test   # Run Rust unit tests (5-10 minutes - NEVER CANCEL)
```

**Flutter Testing:**
```bash
flutter test  # Run Flutter widget tests (2-5 minutes)
```

**Linting and Code Quality:**
```bash
flutter analyze          # Dart/Flutter linting (30-60 seconds)
cd rust && cargo clippy  # Rust linting (2-3 minutes)
```

### Manual Validation Requirements

After building, always perform these validation steps:

1. **Verify application starts:**
   ```bash
   # Windows
   ./build/windows/x64/runner/Release/starcitizen_doctor.exe
   
   # Linux (limited functionality)
   ./build/linux/x64/release/bundle/starcitizen_doctor
   ```

2. **Test core functionality:**
   - Application launches without crashes
   - Main navigation works
   - Settings panel accessible
   - Localization switching functional

**Note:** Full UI testing requires Windows environment. Linux builds have limited functionality.

## Project Structure and Key Files

### Entry Points and Main Code
- **Main application:** `lib/main.dart` - Flutter app entry point with multi-window support
- **App configuration:** `lib/app.dart` - Application state, routing, theming, and localization
- **Rust bridge:** `lib/common/rust/` - Generated Rust-Dart interop code
- **UI modules:** `lib/ui/` - All user interface components organized by feature

### Build Configuration
- **Flutter config:** `pubspec.yaml` - Dependencies, assets, build settings
- **Rust config:** `rust/Cargo.toml` - Native dependencies and build settings
- **Rust bridge:** `flutter_rust_bridge.yaml` - Bridge code generation settings
- **Analysis:** `analysis_options.yaml` - Dart/Flutter linting rules

### Build System Files
- **Rust builder:** `rust_builder/` - Custom Rust compilation integration with cargokit
- **Platform builds:** `windows/`, `linux/`, `macos/` - Platform-specific build configurations
- **CI/CD:** `.github/workflows/windows_nightly.yml` - Automated build pipeline

### Generated Code (DO NOT EDIT)
- `lib/generated/` - Auto-generated localization files
- `lib/**/*.g.dart` - Generated JSON serialization code
- `lib/**/*.freezed.dart` - Generated immutable data classes
- `lib/common/rust/` - Generated Rust-Dart bridge code

## Development Workflow

### Making Changes

1. **For Dart/Flutter changes:**
   ```bash
   # After UI or logic changes
   dart run build_runner build --delete-conflicting-outputs
   flutter analyze
   ```

2. **For Rust changes:**
   ```bash
   cd rust
   cargo check  # Quick validation
   flutter_rust_bridge_codegen generate  # Regenerate bridge if API changed
   ```

3. **For localization changes:**
   ```bash
   flutter pub global run intl_utils:generate
   ```

### Pre-commit Validation

Always run before committing changes:
```bash
flutter analyze                    # Dart linting (required for CI)
cd rust && cargo clippy           # Rust linting  
flutter test                      # Widget tests
cd rust && cargo test            # Rust tests
```

**CI Pipeline will fail if:**
- Flutter analyze reports errors
- Rust clippy reports errors  
- Any tests fail
- Build process fails

## Common Issues and Solutions

### Flutter/Dart Issues
- **Build runner conflicts:** Delete generated files and rebuild with `--delete-conflicting-outputs`
- **Dependency conflicts:** Run `flutter pub deps` to check for version conflicts
- **Localization missing:** Ensure `flutter pub global run intl_utils:generate` completed successfully

### Rust Issues  
- **Bridge generation fails:** Verify flutter_rust_bridge_codegen is installed and Rust code compiles
- **Link errors:** Ensure all required system libraries are installed for target platform
- **API changes:** Regenerate bridge code after modifying Rust API signatures

### Build Performance
- Use `cargo check` instead of `cargo build` for quick Rust validation
- Use `flutter analyze` instead of full build for quick Dart validation
- Clean build artifacts if experiencing issues: `flutter clean && cd rust && cargo clean`

## Application Architecture

**UI Framework:** Flutter with Fluent UI design system for Windows-native appearance
**State Management:** Riverpod with code generation for type-safe state management  
**Routing:** GoRouter for navigation with nested routes
**Localization:** Flutter i18n with custom tooling for community translations
**Data Layer:** Hive for local storage, HTTP client for network requests
**Native Integration:** Rust via flutter_rust_bridge for system operations and performance-critical code

## Key Development Commands Reference

```bash
# Quick development validation (5-10 minutes total)
flutter analyze && cd rust && cargo check

# Full build validation (45-60 minutes - NEVER CANCEL)
flutter pub get && \
dart run build_runner build --delete-conflicting-outputs && \
cd rust && cargo update && cd .. && \
flutter_rust_bridge_codegen generate && \
flutter pub global run intl_utils:generate && \
flutter build windows -v

# Code generation only (5-10 minutes)
dart run build_runner build --delete-conflicting-outputs && \
flutter_rust_bridge_codegen generate && \
flutter pub global run intl_utils:generate

# Test execution (10-15 minutes total - NEVER CANCEL)
flutter test && cd rust && cargo test
```

**CRITICAL REMINDERS:**
- NEVER CANCEL builds or long-running commands - they can take 45+ minutes
- Always set command timeouts to 60+ minutes for build operations
- Always set command timeouts to 30+ minutes for test operations  
- Validate changes with both quick checks and full builds before committing
- Use Windows environment for complete functionality testing