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

   sudo gem install cocoapods
   

Installation

1. Verify Flutter Installation

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

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

3. Install Dependencies

flutter pub get

4. Generate Code

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

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

For continuous code generation during development:

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

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:

   flutter emulators --launch <emulator_id>
   

2. Run the app:

   flutter run
   

On iOS Simulator (macOS only)

1. Start iOS simulator:

   open -a Simulator
   

2. Run the app:

   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:

   flutter devices
   

4. Run the app:

   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)

   # 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

   flutter pub run build_runner build
   

3. Run App

   flutter run
   

2. Code Generation

The app uses several code generators:

Freezed (Immutable Models)

// 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)

// 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

flutter test

Run Specific Test File

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

Run Tests with Coverage

flutter test --coverage

View coverage report:

genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

Widget Tests

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

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

Integration Tests

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

# 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

# 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

# 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

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:

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

Troubleshooting

Flutter Doctor Issues

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

# 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

# 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):

{
  "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:

# 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:

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

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! 🚀