geutebruck/geutebruck-api/specs/001-flutter-app/quickstart.md

# Geutebruck API Flutter App - Quick Start Guide

## Prerequisites

Before you begin, ensure you have the following installed:

### Required Software

1. **Flutter SDK 3.24+**
   - Download from: https://flutter.dev/docs/get-started/install
   - Add to PATH: `C:\Users\{username}\develop\flutter\bin`

2. **Git for Windows**
   - Download from: https://git-scm.com/downloads/win

3. **Code Editor**
   - Recommended: Visual Studio Code with Flutter extension
   - Alternative: Android Studio

### Platform-Specific Requirements

#### For Android Development

1. **Android Studio**
   - Download from: https://developer.android.com/studio
   - Install Android SDK
   - Install Android SDK Build-Tools
   - Install Android Emulator

2. **Java JDK 11+**
   - Download from: https://www.oracle.com/java/technologies/downloads/

#### For iOS Development (macOS only)

1. **Xcode 14+**
   - Download from Mac App Store
   - Install Xcode Command Line Tools

2. **CocoaPods**
   ```bash
   sudo gem install cocoapods
   ```

## Installation

### 1. Verify Flutter Installation

```bash
flutter doctor
```

Expected output should show checkmarks for:
- Flutter (Channel stable)
- Android toolchain
- Chrome (for web development)
- Visual Studio Code
- Connected device

### 2. Clone the Repository

```bash
cd C:\DEV\COPILOT
git clone <repository-url> geutebruck_app
cd geutebruck_app
```

### 3. Install Dependencies

```bash
flutter pub get
```

### 4. Generate Code

The app uses code generation for models, BLoCs, and dependency injection:

```bash
flutter pub run build_runner build --delete-conflicting-outputs
```

For continuous code generation during development:

```bash
flutter pub run build_runner watch --delete-conflicting-outputs
```

### 5. Configure API Endpoint

Edit the API configuration file:

**File:** `lib/core/constants/api_constants.dart`

```dart
class ApiConstants {
  static const String baseUrl = 'http://localhost:8000';  // Change to your API URL
  static const Duration timeout = Duration(seconds: 30);
}
```

## Running the App

### On Android Emulator

1. Start Android emulator:
   ```bash
   flutter emulators --launch <emulator_id>
   ```

2. Run the app:
   ```bash
   flutter run
   ```

### On iOS Simulator (macOS only)

1. Start iOS simulator:
   ```bash
   open -a Simulator
   ```

2. Run the app:
   ```bash
   flutter run
   ```

### On Physical Device

1. Enable USB debugging on your device (Android)
   - Settings → About Phone → Tap Build Number 7 times
   - Settings → Developer Options → Enable USB Debugging

2. Connect device via USB

3. Verify device is detected:
   ```bash
   flutter devices
   ```

4. Run the app:
   ```bash
   flutter run
   ```

### Hot Reload During Development

While the app is running:
- Press `r` to hot reload
- Press `R` to hot restart
- Press `q` to quit

## Development Workflow

### 1. Feature Development

Follow this workflow for each feature:

1. **Write Tests First (TDD)**
   ```bash
   # Create test file
   test/domain/use_cases/servers/get_servers_test.dart

   # Run test (will fail)
   flutter test test/domain/use_cases/servers/get_servers_test.dart

   # Implement feature
   lib/domain/use_cases/servers/get_servers.dart

   # Run test (should pass)
   flutter test test/domain/use_cases/servers/get_servers_test.dart
   ```

2. **Generate Code**
   ```bash
   flutter pub run build_runner build
   ```

3. **Run App**
   ```bash
   flutter run
   ```

### 2. Code Generation

The app uses several code generators:

#### Freezed (Immutable Models)

```dart
// Define model
@freezed
class Server with _$Server {
  const factory Server({
    required String id,
    required String alias,
  }) = _Server;

  factory Server.fromJson(Map<String, dynamic> json) =>
      _$ServerFromJson(json);
}

// Generate with:
flutter pub run build_runner build
```

#### Injectable (Dependency Injection)

```dart
// Annotate class
@injectable
class ServerRepository {
  final ServerRemoteDataSource remoteDataSource;

  ServerRepository(this.remoteDataSource);
}

// Register in injection.dart:
@InjectableInit()
void configureDependencies() => getIt.init();

// Generate with:
flutter pub run build_runner build
```

### 3. Testing

#### Run All Tests

```bash
flutter test
```

#### Run Specific Test File

```bash
flutter test test/domain/use_cases/servers/get_servers_test.dart
```

#### Run Tests with Coverage

```bash
flutter test --coverage
```

View coverage report:
```bash
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html
```

#### Widget Tests

```dart
testWidgets('ServerListScreen displays servers', (tester) async {
  await tester.pumpWidget(
    MaterialApp(home: ServerListScreen()),
  );

  expect(find.text('Servers'), findsOneWidget);
});
```

#### Integration Tests

```bash
flutter test integration_test/app_test.dart
```

## Project Structure

```
lib/
├── core/                    # Core utilities and configurations
│   ├── constants/
│   ├── errors/
│   ├── network/
│   └── theme/
├── data/                    # Data layer
│   ├── models/             # JSON serializable models
│   ├── repositories/       # Repository implementations
│   └── data_sources/       # Remote and local data sources
├── domain/                  # Domain layer
│   ├── entities/           # Business entities
│   ├── repositories/       # Repository interfaces
│   └── use_cases/          # Business logic
├── presentation/            # Presentation layer
│   ├── blocs/              # BLoC state management
│   ├── screens/            # Full-page screens
│   └── widgets/            # Reusable widgets
├── injection.dart           # Dependency injection setup
└── main.dart               # App entry point
```

## Common Commands

### Development

```bash
# Run app in debug mode
flutter run

# Run app in profile mode (for performance testing)
flutter run --profile

# Run app in release mode
flutter run --release

# Clean build artifacts
flutter clean

# Update dependencies
flutter pub upgrade

# Check for outdated packages
flutter pub outdated

# Analyze code
flutter analyze
```

### Building

```bash
# Build Android APK
flutter build apk --release

# Build Android App Bundle (for Play Store)
flutter build appbundle --release

# Build iOS (macOS only)
flutter build ipa --release
```

### Debugging

```bash
# Run with DevTools
flutter run --devtools

# Attach debugger to running app
flutter attach

# Get device logs
flutter logs
```

## Environment Configuration

### Development Environment

**File:** `lib/core/config/env_config.dart`

```dart
enum Environment { development, staging, production }

class EnvConfig {
  static Environment currentEnv = Environment.development;

  static String get apiBaseUrl {
    switch (currentEnv) {
      case Environment.development:
        return 'http://localhost:8000';
      case Environment.staging:
        return 'https://staging-api.geutebruck.com';
      case Environment.production:
        return 'https://api.geutebruck.com';
    }
  }
}
```

Switch environments:

```dart
// In main.dart
void main() {
  EnvConfig.currentEnv = Environment.production;
  runApp(MyApp());
}
```

## Troubleshooting

### Flutter Doctor Issues

```bash
flutter doctor -v
```

Common fixes:
- **Android license not accepted**: `flutter doctor --android-licenses`
- **Xcode not configured**: `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`

### Build Runner Issues

```bash
# Clean and rebuild
flutter clean
flutter pub get
flutter pub run build_runner clean
flutter pub run build_runner build --delete-conflicting-outputs
```

### Dependency Conflicts

```bash
# Clear pub cache
flutter pub cache repair

# Clean and reinstall
flutter clean
rm pubspec.lock
flutter pub get
```

### Hot Reload Not Working

- Try hot restart (press `R`)
- Check for syntax errors
- Some changes require full restart (native code, assets)

### Emulator Performance

For better Android emulator performance:
1. Enable hardware acceleration (Intel HAXM or AMD Hypervisor)
2. Allocate more RAM to emulator (4GB+)
3. Use x86/x64 system images (not ARM)

## IDE Setup

### Visual Studio Code

Install extensions:
1. Flutter
2. Dart
3. Flutter Intl (for internationalization)
4. Error Lens
5. GitLens

**Settings (.vscode/settings.json):**

```json
{
  "dart.lineLength": 120,
  "editor.formatOnSave": true,
  "dart.debugExternalPackageLibraries": false,
  "dart.debugSdkLibraries": false,
  "[dart]": {
    "editor.formatOnSave": true,
    "editor.formatOnType": true,
    "editor.rulers": [120],
    "editor.selectionHighlight": false,
    "editor.suggest.snippetsPreventQuickSuggestions": false,
    "editor.suggestSelection": "first",
    "editor.tabCompletion": "onlySnippets",
    "editor.wordBasedSuggestions": false
  }
}
```

### Android Studio

Install plugins:
1. Flutter
2. Dart

Configure:
- File → Settings → Languages & Frameworks → Flutter
- Set Flutter SDK path

## API Testing

Before running the app, ensure the backend API is running:

```bash
# Start API server
cd C:\DEV\COPILOT\geutebruck-api
python -m uvicorn src.api.main:app --host 0.0.0.0 --port 8000

# Verify API is accessible
curl http://localhost:8000/api/v1/health
```

Test authentication:

```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

## Continuous Integration

### GitHub Actions

**File:** `.github/workflows/flutter.yml`

```yaml
name: Flutter CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.0'
          channel: 'stable'

      - name: Install dependencies
        run: flutter pub get

      - name: Generate code
        run: flutter pub run build_runner build --delete-conflicting-outputs

      - name: Analyze
        run: flutter analyze

      - name: Run tests
        run: flutter test --coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

  build:
    runs-on: ubuntu-latest
    needs: test

    steps:
      - uses: actions/checkout@v3

      - name: Setup Flutter
        uses: subosito/flutter-action@v2

      - name: Build APK
        run: flutter build apk --release

      - name: Upload APK
        uses: actions/upload-artifact@v3
        with:
          name: app-release.apk
          path: build/app/outputs/flutter-apk/app-release.apk
```

## Next Steps

1. **Review Specifications**
   - Read `constitution.md` for coding standards
   - Review `spec.md` for user stories
   - Study `plan.md` for architecture

2. **Start Development**
   - Begin with Phase 1 tasks in `tasks.md`
   - Follow TDD approach (tests first)
   - Use code generation for models and DI

3. **Join the Team**
   - Set up development environment
   - Clone repository
   - Create feature branch
   - Start with assigned tasks

## Support

For issues or questions:
- Check Flutter documentation: https://flutter.dev/docs
- BLoC documentation: https://bloclibrary.dev
- Project-specific questions: See team lead

---

**Happy Coding! 🚀**