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)

# Clone backend or download the spec
git clone <backend-repo>
# Spec location: backend/docs/openapi.json

Step 2: Install Generator (30 seconds)

# Choose one:
brew install openapi-generator                    # macOS
npm install -g @openapitools/openapi-generator-cli  # Cross-platform

Step 3: Generate Client (20 seconds)

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)

# pubspec.yaml
dependencies:
  http: ^1.1.0
  flutter_secure_storage: ^9.0.0
  flutter_riverpod: ^2.4.9
  flutter_dotenv: ^5.1.0

flutter pub get

Step 5: Create API Client (2 minutes)

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

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

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

request.headers['Authorization'] = 'Bearer $token';

---

Android Network Setup

<!-- android/app/src/main/AndroidManifest.xml -->
<application android:usesCleartextTraffic="true">

Use http://10.0.2.2:5246 for Android emulator

---

When Backend Updates

# 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