iperf3-gui/.hermes/plans/2025-08-24_1200-iperf3-gui-mvp.md

# iperf3-gui Implementation Plan

> **Status:** COMPLETED
> **Last updated:** 2025-08-24 14:30 UTC+09:00

**Goal:** Create a Flutter Android app that bundles iperf3 and provides a simple GUI for client-mode network throughput testing.

## Completed Tasks

### Task 1: Scaffold Flutter project ✅
- Created project with `flutter create` using org `novoyuuparosk`
- Package: `com.novoyuuparosk.iperf3gui`
- Kotlin for Android, Swift for iOS
- Commit: `815fc48`

### Task 2: Add dependencies and configure analysis ✅
- Dependencies: `provider: ^6.1.2`, `path_provider: ^2.1.4`
- Dev dependencies: `flutter_lints: ^6.0.0`, `flutter_test`
- Strict analysis options (strict-casts, strict-inference, strict-raw-types)
- Commit: `815fc48`

### Task 3: Domain models ✅
- `TestConfiguration`: server, port, duration, interval, parallelStreams, validation
- `Iperf3Result`: rawOutput, exitCode
- Unit tests for both models (5 tests)
- Commit: `815fc48`

### Task 4: iperf3 binary service ✅
- `Iperf3Service`: spawns Process with CLI args from TestConfiguration
- Captures stdout/stderr, returns Iperf3Result
- Commit: `815fc48`

### Task 5: TestRunViewModel ✅
- State enum: idle, running, completed, error
- Methods: runTest(), reset()
- ChangeNotifier for UI updates
- 4 unit tests (4 tests)
- Commit: `815fc48`

### Task 6: Main test screen UI ✅
- TextField for server (default: iperf.es.net)
- TextField for port (default: 5201)
- ElevatedButton "GO" with loading indicator
- Status text indicator
- Raw output TextField (read-only)
- Provider integration for state management
- Commit: `815fc48`

### Task 7: Bundle iperf3 binaries 🟡
- Directory structure created: `assets/iperf3/arm64-v8a/`, `assets/iperf3/armeabi-v7a/`
- Downloading pre-built binaries failed (404 on gh-pages)
- Attempted to build from source but NDK missing OpenSSL headers
- **TODO:** Build iperf3 binaries separately (see README for instructions) or obtain pre-built binaries
- Commit: `3ba1133`

### Task 8: README ✅
- Project description and features
- Architecture overview with tree diagram
- Build instructions
- License info (MIT, iperf3 is BSD-3-Clause)
- Commit: `3ba1133`

### Task 9: CI workflow ✅
- GitHub Actions workflow for analyze + tests
- Triggers on push/PR to master
- Uses Flutter 3.47.1 stable
- Commit: `3ba1133`

### Task 10: Push to Gitea ✅
- Pushed to `ssh://git@pi5-16.local:2222/android-stuff/iperf3-gui.git`
- Remote: `origin`
- Branch: `master`
- All commits pushed successfully
- Commit: `3ba1133`

## Verification

```
$ flutter analyze
No issues found! (ran in 0.4s)

$ flutter test
00:00 +0: loading /home/hermes/dev/android-stuff/iperf3-gui/test/widget_test.dart
...
00:00 +10: All tests passed!
```

## Remaining Work

### High Priority
- **[Task 7b]** Obtain working iperf3 v3.21 binaries for Android arm64-v8a/armeabi-v7a
  - Options: build with NDK + OpenSSL, or find pre-built binaries
  - See README for build instructions
  - Update `pubspec.yaml` to include assets in `flutter` section

### Future Enhancements
- Add server-mode support (dual client/server toggle)
- Add result parsing/formatting (extract bandwidth, loss, jitter)
- Add history of past tests
- Add settings screen for advanced options (UDP, parallel streams, etc.)
- Add JSON output support for machine-readable results
- Add proper splash screen and app icon
- Add proguard/r8 configuration for release builds
- Add instrumentation tests for UI components

## Project Structure

```
iperf3-gui/
├── .github/workflows/
│   └── ci.yaml                 # CI: analyze + test
├── .hermes/plans/
│   └── 2025-08-24_1200-iperf3-gui-mvp.md  # This plan
├── assets/
│   └── iperf3/                 # Bundled binaries (TODO)
│       ├── arm64-v8a/
│       └── armeabi-v7a/
├── lib/
│   ├── domain/
│   │   ├── models/
│   │   │   ├── test_configuration.dart  # Test config with validation
│   │   │   └── iperf3_result.dart       # Raw result from iperf3
│   │   └── services/
│   │       └── iperf3_service.dart      # Process runner for iperf3
│   ├── ui/
│   │   └── features/
│   │       └── test_run/
│   │           ├── test_run_screen.dart      # UI screen
│   │           └── test_run_view_model.dart  # State management
│   ├── data/
│   │   └── services/
│   │       ├── iperf3_service.dart           # (also in domain)
│   │       └── iperf3_binary_path_provider.dart  # Extracts binary from assets
│   └── main.dart                             # App entry point
├── test/
│   ├── widget_test.dart                      # Smoke test
│   ├── domain/models/
│   │   ├── test_configuration_test.dart      # Config tests
│   │   └── iperf3_result_test.dart           # Result tests
│   └── ui/features/test_run/
│       └── test_run_view_model_test.dart     # ViewModel tests
├── android/
│   ├── app/src/main/kotlin/novoyuuparosk/iperf3gui/
│   │   └── MainActivity.kt
│   └── app/build.gradle.kts
│       ├── applicationId = "com.novoyuuparosk.iperf3gui"
├── pubspec.yaml
├── analysis_options.yaml
├── README.md
└── .gitignore
```

## Commit History

```
3ba1133 feat: add CI workflow and update README
815fc48 refactor: fix lint issues and wire up main screen
e63c4b9 feat: add TestRunViewModel with state management
7c6d2a7 feat: add domain models for test configuration and results
c4b3a12 chore: scaffold Flutter project with com.novoyuuparosk.iperf3gui package
5bc59a9 Initial commit
```

## Gitea URL

https://git.novoyuuparosk.org/android-stuff/iperf3-gui