CODEX_ADK/BACKEND/.claude-docs/FLUTTER-QUICK-START.md

# Flutter Team: 5-Minute Quick Start

## TL;DR
Backend provides `docs/openapi.json` → You generate Dart client → Build your app

---

## Step 1: Get OpenAPI Spec (10 seconds)
```bash
# Clone backend or download the spec
git clone <backend-repo>
# Spec location: backend/docs/openapi.json
```

## Step 2: Install Generator (30 seconds)
```bash
# Choose one:
brew install openapi-generator                    # macOS
npm install -g @openapitools/openapi-generator-cli  # Cross-platform
```

## Step 3: Generate Client (20 seconds)
```bash
cd your-flutter-app

openapi-generator-cli generate \
  -i ../backend/docs/openapi.json \
  -g dart \
  -o lib/api/generated \
  --additional-properties=pubName=codex_api_client
```

## Step 4: Add Dependencies (30 seconds)
```yaml
# pubspec.yaml
dependencies:
  http: ^1.1.0
  flutter_secure_storage: ^9.0.0
  flutter_riverpod: ^2.4.9
  flutter_dotenv: ^5.1.0
```

```bash
flutter pub get
```

## Step 5: Create API Client (2 minutes)
```dart
// lib/services/api_client.dart
import 'package:http/http.dart' as http;

class ApiClient extends http.BaseClient {
  final http.Client _client = http.Client();
  final String baseUrl = 'http://localhost:5246';

  @override
  Future<http.StreamedResponse> send(http.BaseRequest request) async {
    request.headers['Content-Type'] = 'application/json';
    return await _client.send(request);
  }
}
```

## Step 6: Use It! (1 minute)
```dart
import 'package:codex_api_client/api.dart';

// Create client
final apiClient = ApiClient();
final api = DefaultApi(apiClient, 'http://localhost:5246');

// Call health check
final isHealthy = await api.apiQueryHealthPost(healthQuery: HealthQuery());
print('API Healthy: $isHealthy'); // true
```

---

## Important CQRS Concepts

### All Endpoints Use JSON Body
```dart
// Even empty requests need a body
await api.apiQueryHealthPost(healthQuery: HealthQuery()); // ✅
await api.apiQueryHealthPost();  // ❌ Wrong
```

### Endpoint Patterns
- Queries: `POST /api/query/{name}` or `GET /api/query/{name}`
- Commands: `POST /api/command/{name}`
- Lists: `POST /api/dynamicquery/{type}`

### Authentication (when implemented)
```dart
request.headers['Authorization'] = 'Bearer $token';
```

---

## Android Network Setup
```xml
<!-- android/app/src/main/AndroidManifest.xml -->
<application android:usesCleartextTraffic="true">
```

Use `http://10.0.2.2:5246` for Android emulator

---

## When Backend Updates
```bash
# 1. Pull backend changes
cd ../backend && git pull

# 2. Check for breaking changes
cat docs/CHANGELOG.md

# 3. Regenerate client
cd ../flutter-app
openapi-generator-cli generate -i ../backend/docs/openapi.json -g dart -o lib/api/generated

# 4. Test
flutter test
```

---

## Full Documentation
See `.claude-docs/FLUTTER-INTEGRATION.md` for complete guide with:
- Riverpod state management
- Error handling
- Testing
- CI/CD
- Best practices

---

## Backend Contacts
- **OpenAPI Spec:** `backend/docs/openapi.json`
- **Breaking Changes:** `backend/docs/CHANGELOG.md`
- **Swagger UI:** http://localhost:5246/swagger
- **Questions:** Check `backend/docs/README.md`