229a0698a3
Multi-agent AI laboratory with ASP.NET Core 8.0 backend and Flutter frontend. Implements CQRS architecture, OpenAPI contract-first API design. BACKEND: Agent management, conversations, executions with PostgreSQL + Ollama FRONTEND: Cross-platform UI with strict typing and Result-based error handling Co-Authored-By: Jean-Philippe Brule <jp@svrnty.io>
143 lines
3.0 KiB
Markdown
143 lines
3.0 KiB
Markdown
# 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');
|
|
```
|
|
|
|
---
|
|
|
|
## Important CQRS Concepts
|
|
|
|
### All Endpoints Use JSON Body
|
|
```dart
|
|
// Even empty requests need a body
|
|
await api.apiQueryHealthPost(healthQuery: HealthQuery()); // Correct
|
|
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`
|