my_app

commit 229a0698a37dd9818154f8b3c89bd32c37a3de52 Author: Svrnty Date: Sun Oct 26 23:12:32 2025 -0400 Initial commit: CODEX_ADK monorepo 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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4697f93 --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# ============================================================================== +# CODEX_ADK Root .gitignore +# ============================================================================== +# This is a monorepo combining BACKEND (ASP.NET Core) and FRONTEND (Flutter) +# Each subdirectory has its own .gitignore for component-specific exclusions +# ============================================================================== + +# IDE & Editor - Global +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS Files - Global +.DS_Store +Thumbs.db +._* + +# Temporary Files +*.tmp +*.temp +*.bak + +# Documentation drafts (keep finalized docs) +DRAFT_*.md +TODO_*.md +NOTES_*.md + +# Local environment overrides +.env.local +.env.*.local + +# Git helper files +.git-credentials + +# Project-specific exclusions +# (BACKEND and FRONTEND have their own .gitignore files) diff --git a/BACKEND/.claude-docs/FLUTTER-INTEGRATION.md b/BACKEND/.claude-docs/FLUTTER-INTEGRATION.md new file mode 100644 index 0000000..8645b44 --- /dev/null +++ b/BACKEND/.claude-docs/FLUTTER-INTEGRATION.md @@ -0,0 +1,961 @@ +# Flutter Frontend: Complete API Integration Guide + +## Objective +Integrate your Flutter app with the Codex CQRS-based ASP.NET Core API using type-safe Dart clients generated from OpenAPI specification. + +--- + +## Prerequisites + +- Flutter SDK 3.0+ installed +- Dart 3.0+ +- Git access to backend repository +- VS Code with Flutter/Dart extensions or Android Studio +- Basic understanding of REST APIs and Dart + +--- + +## Architecture Overview + +The Codex API uses **CQRS pattern** with OpenHarbor.CQRS framework: + +- **Queries** (Read): `POST /api/query/{queryName}` or `GET /api/query/{queryName}` +- **Commands** (Write): `POST /api/command/{commandName}` +- **Dynamic Queries** (Paginated): `POST /api/dynamicquery/{itemType}` + +All requests use JSON payloads (even for empty requests). + +--- + +## Step 1: Access OpenAPI Specification + +### Get the Spec File + +```bash +# Option A: Clone backend repository +git clone +cd backend + +# The spec is located at: docs/openapi.json + +# Option B: Download from running API +curl http://localhost:5246/swagger/v1/swagger.json -o openapi.json +``` + +### Review Documentation +Before coding, read: +- `backend/docs/ARCHITECTURE.md` - Understand CQRS patterns +- `backend/docs/CHANGELOG.md` - Check for breaking changes +- `backend/docs/openapi.json` - Your API contract + +--- + +## Step 2: Generate Dart API Client + +### Install OpenAPI Generator + +```bash +# Install via Homebrew (macOS) +brew install openapi-generator + +# Or via npm +npm install -g @openapitools/openapi-generator-cli + +# Or use Docker +docker pull openapitools/openapi-generator-cli +``` + +### Generate Dart Client + +```bash +# Navigate to your Flutter project +cd /path/to/your/flutter-app + +# Create API directory +mkdir -p lib/api + +# Generate Dart client +openapi-generator-cli generate \ + -i ../backend/docs/openapi.json \ + -g dart \ + -o lib/api/generated \ + --additional-properties=pubName=codex_api_client,pubLibrary=codex_api_client + +# If using Docker: +docker run --rm \ + -v ${PWD}:/local openapitools/openapi-generator-cli generate \ + -i /local/../backend/docs/openapi.json \ + -g dart \ + -o /local/lib/api/generated \ + --additional-properties=pubName=codex_api_client,pubLibrary=codex_api_client +``` + +This generates: +- `lib/api/generated/lib/api.dart` - API client +- `lib/api/generated/lib/model/` - DTOs and models +- `lib/api/generated/doc/` - API documentation + +--- + +## Step 3: Configure Flutter Project + +### Update pubspec.yaml + +Add required dependencies: + +```yaml +name: your_flutter_app +description: Your Flutter app description + +environment: + sdk: '>=3.0.0 <4.0.0' + +dependencies: + flutter: + sdk: flutter + + # HTTP client + http: ^1.1.0 + + # JSON serialization + json_annotation: ^4.8.1 + + # State management (choose one) + flutter_riverpod: ^2.4.9 # Recommended + # provider: ^6.1.1 + # bloc: ^8.1.3 + + # Secure storage for tokens + flutter_secure_storage: ^9.0.0 + + # Environment configuration + flutter_dotenv: ^5.1.0 + +dev_dependencies: + flutter_test: + sdk: flutter + + build_runner: ^2.4.7 + json_serializable: ^6.7.1 + flutter_lints: ^3.0.1 + mockito: ^5.4.4 + +flutter: + uses-material-design: true + + # Add environment files + assets: + - .env + - .env.development + - .env.production +``` + +### Run pub get + +```bash +flutter pub get +cd lib/api/generated +flutter pub get +cd ../../.. +``` + +--- + +## Step 4: Setup Environment Configuration + +### Create Environment Files + +**`.env.development`:** +```env +API_BASE_URL=http://localhost:5246 +API_TIMEOUT=30000 +``` + +**`.env.production`:** +```env +API_BASE_URL=https://api.yourapp.com +API_TIMEOUT=30000 +``` + +**`.env` (default/local):** +```env +API_BASE_URL=http://localhost:5246 +API_TIMEOUT=30000 +``` + +### Create Config Class + +**`lib/config/api_config.dart`:** +```dart +import 'package:flutter_dotenv/flutter_dotenv.dart'; + +class ApiConfig { + static String get baseUrl => dotenv.env['API_BASE_URL'] ?? 'http://localhost:5246'; + static int get timeout => int.parse(dotenv.env['API_TIMEOUT'] ?? '30000'); + + static const String apiVersion = 'v1'; +} +``` + +### Initialize in main.dart + +**`lib/main.dart`:** +```dart +import 'package:flutter/material.dart'; +import 'package:flutter_dotenv/flutter_dotenv.dart'; +import 'package:flutter_riverpod/flutter_riverpod.dart'; + +Future main() async { + WidgetsFlutterBinding.ensureInitialized(); + + // Load environment variables + await dotenv.load(fileName: ".env"); + + runApp( + const ProviderScope( + child: MyApp(), + ), + ); +} + +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'Codex App', + theme: ThemeData( + primarySwatch: Colors.blue, + useMaterial3: true, + ), + home: const HomePage(), + ); + } +} +``` + +--- + +## Step 5: Create API Client Service + +### Create HTTP Client with Interceptors + +**`lib/services/api_client.dart`:** +```dart +import 'package:http/http.dart' as http; +import 'package:flutter_secure_storage/flutter_secure_storage.dart'; +import '../config/api_config.dart'; + +class ApiClient extends http.BaseClient { + final http.Client _client = http.Client(); + final FlutterSecureStorage _storage = const FlutterSecureStorage(); + + @override + Future send(http.BaseRequest request) async { + // Add base URL if not already present + if (!request.url.toString().startsWith('http')) { + request = _updateRequestUrl(request); + } + + // Add authentication token + final token = await _storage.read(key: 'auth_token'); + if (token != null && token.isNotEmpty) { + request.headers['Authorization'] = 'Bearer $token'; + } + + // Add default headers + request.headers['Content-Type'] = 'application/json'; + request.headers['Accept'] = 'application/json'; + + print('REQUEST ${request.method} ${request.url}'); + + try { + final response = await _client.send(request); + print('RESPONSE ${response.statusCode} ${request.url}'); + return response; + } catch (e) { + print('ERROR Request failed: $e'); + rethrow; + } + } + + http.BaseRequest _updateRequestUrl(http.BaseRequest request) { + final newUri = Uri.parse('${ApiConfig.baseUrl}${request.url.path}'); + + if (request is http.Request) { + final newRequest = http.Request(request.method, newUri) + ..headers.addAll(request.headers) + ..body = request.body; + return newRequest; + } + + throw UnsupportedError('Unsupported request type'); + } + + Future setAuthToken(String token) async { + await _storage.write(key: 'auth_token', value: token); + } + + Future clearAuthToken() async { + await _storage.delete(key: 'auth_token'); + } + + Future getAuthToken() async { + return await _storage.read(key: 'auth_token'); + } +} +``` + +--- + +## Step 6: Create Service Layer (Repository Pattern) + +### Health Query Service Example + +**`lib/services/health_service.dart`:** +```dart +import 'package:codex_api_client/api.dart'; +import '../models/api_result.dart'; +import 'api_client.dart'; + +class HealthService { + final ApiClient _apiClient; + late final DefaultApi _api; + + HealthService(this._apiClient) { + _api = DefaultApi(_apiClient, ApiConfig.baseUrl); + } + + /// Check if API is healthy + Future> checkHealth() async { + try { + // Call POST /api/query/health + final response = await _api.apiQueryHealthPost( + healthQuery: HealthQuery(), // Empty query object + ); + + return ApiResult.success(response ?? false); + } on ApiException catch (e) { + return ApiResult.failure( + message: e.message ?? 'Health check failed', + statusCode: e.code, + ); + } catch (e) { + return ApiResult.failure( + message: 'Network error: $e', + ); + } + } +} +``` + +### Create ApiResult Model + +**`lib/models/api_result.dart`:** +```dart +class ApiResult { + final T? data; + final String? errorMessage; + final int? statusCode; + final Map>? validationErrors; + + bool get isSuccess => errorMessage == null; + bool get isFailure => !isSuccess; + + ApiResult.success(this.data) + : errorMessage = null, + statusCode = null, + validationErrors = null; + + ApiResult.failure({ + required String message, + this.statusCode, + this.validationErrors, + }) : data = null, + errorMessage = message; + + /// Handle the result with callbacks + R when({ + required R Function(T data) success, + required R Function(String message) failure, + }) { + if (isSuccess && data != null) { + return success(data as T); + } else { + return failure(errorMessage ?? 'Unknown error'); + } + } +} +``` + +--- + +## Step 7: Integrate with Riverpod (State Management) + +### Create Providers + +**`lib/providers/api_providers.dart`:** +```dart +import 'package:flutter_riverpod/flutter_riverpod.dart'; +import '../services/api_client.dart'; +import '../services/health_service.dart'; + +// API Client Provider +final apiClientProvider = Provider((ref) { + return ApiClient(); +}); + +// Health Service Provider +final healthServiceProvider = Provider((ref) { + final apiClient = ref.watch(apiClientProvider); + return HealthService(apiClient); +}); + +// Health Check Provider (auto-fetches) +final healthCheckProvider = FutureProvider((ref) async { + final healthService = ref.watch(healthServiceProvider); + final result = await healthService.checkHealth(); + + return result.when( + success: (isHealthy) => isHealthy, + failure: (_) => false, + ); +}); +``` + +### Use in UI + +**`lib/screens/home_screen.dart`:** +```dart +import 'package:flutter/material.dart'; +import 'package:flutter_riverpod/flutter_riverpod.dart'; +import '../providers/api_providers.dart'; + +class HomeScreen extends ConsumerWidget { + const HomeScreen({super.key}); + + @override + Widget build(BuildContext context, WidgetRef ref) { + final healthCheck = ref.watch(healthCheckProvider); + + return Scaffold( + appBar: AppBar( + title: const Text('Codex App'), + actions: [ + // API Health Indicator + healthCheck.when( + data: (isHealthy) => Icon( + isHealthy ? Icons.check_circle : Icons.error, + color: isHealthy ? Colors.green : Colors.red, + ), + loading: () => const CircularProgressIndicator(), + error: (_, __) => const Icon(Icons.error, color: Colors.red), + ), + const SizedBox(width: 16), + ], + ), + body: Center( + child: Column( + mainAxisAlignment: MainAxisAlignment.center, + children: [ + healthCheck.when( + data: (isHealthy) => Text( + isHealthy ? 'API Connected' : 'API Disconnected', + style: Theme.of(context).textTheme.headlineSmall, + ), + loading: () => const CircularProgressIndicator(), + error: (error, _) => Text('Error: $error'), + ), + ], + ), + ), + ); + } +} +``` + +--- + +## Step 8: Handle CQRS Commands and Queries + +### Example: User Command Service + +**`lib/services/user_service.dart`:** +```dart +import 'package:codex_api_client/api.dart'; +import '../models/api_result.dart'; +import 'api_client.dart'; + +class UserService { + final ApiClient _apiClient; + late final DefaultApi _api; + + UserService(this._apiClient) { + _api = DefaultApi(_apiClient, ApiConfig.baseUrl); + } + + /// Create a new user (Command) + Future> createUser({ + required String username, + required String email, + required String password, + }) async { + try { + await _api.apiCommandCreateuserPost( + createUserCommand: CreateUserCommand( + username: username, + email: email, + password: password, + ), + ); + + return ApiResult.success(null); + } on ApiException catch (e) { + return _handleApiException(e); + } catch (e) { + return ApiResult.failure(message: 'Network error: $e'); + } + } + + /// Get paginated users (Dynamic Query) + Future>> getUsers({ + int page = 1, + int pageSize = 20, + String? searchTerm, + }) async { + try { + final filters = searchTerm != null && searchTerm.isNotEmpty + ? [ + DynamicQueryFilter( + path: 'username', + type: FilterType.contains, + value: searchTerm, + ), + ] + : []; + + final response = await _api.apiDynamicqueryUserPost( + dynamicQuery: DynamicQuery( + page: page, + pageSize: pageSize, + filters: filters, + sorts: [ + DynamicQuerySort( + path: 'createdAt', + descending: true, + ), + ], + ), + ); + + return ApiResult.success(response); + } on ApiException catch (e) { + return _handleApiException(e); + } catch (e) { + return ApiResult.failure(message: 'Network error: $e'); + } + } + + ApiResult _handleApiException(ApiException e) { + switch (e.code) { + case 400: + // Validation errors from FluentValidation + return ApiResult.failure( + message: 'Validation failed', + statusCode: 400, + validationErrors: _parseValidationErrors(e.message), + ); + case 401: + return ApiResult.failure( + message: 'Unauthorized. Please log in.', + statusCode: 401, + ); + case 403: + return ApiResult.failure( + message: 'Permission denied', + statusCode: 403, + ); + case 404: + return ApiResult.failure( + message: 'Resource not found', + statusCode: 404, + ); + case 500: + return ApiResult.failure( + message: 'Server error. Please try again.', + statusCode: 500, + ); + default: + return ApiResult.failure( + message: e.message ?? 'Unknown error', + statusCode: e.code, + ); + } + } + + Map>? _parseValidationErrors(String? message) { + // Parse validation errors from response + // Format depends on backend's error response structure + return null; + } +} +``` + +--- + +## Step 9: Testing + +### Unit Tests + +**`test/services/health_service_test.dart`:** +```dart +import 'package:flutter_test/flutter_test.dart'; +import 'package:mockito/mockito.dart'; +import 'package:mockito/annotations.dart'; +import 'package:your_app/services/health_service.dart'; +import 'package:your_app/services/api_client.dart'; + +@GenerateMocks([ApiClient]) +import 'health_service_test.mocks.dart'; + +void main() { + late HealthService healthService; + late MockApiClient mockApiClient; + + setUp(() { + mockApiClient = MockApiClient(); + healthService = HealthService(mockApiClient); + }); + + group('HealthService', () { + test('checkHealth returns true when API is healthy', () async { + // Arrange + when(mockApiClient.send(any)).thenAnswer( + (_) async => http.StreamedResponse( + Stream.value(utf8.encode('true')), + 200, + ), + ); + + // Act + final result = await healthService.checkHealth(); + + // Assert + expect(result.isSuccess, true); + expect(result.data, true); + }); + + test('checkHealth returns failure on error', () async { + // Arrange + when(mockApiClient.send(any)).thenThrow(Exception('Network error')); + + // Act + final result = await healthService.checkHealth(); + + // Assert + expect(result.isFailure, true); + expect(result.errorMessage, contains('Network error')); + }); + }); +} +``` + +### Integration Tests + +**`integration_test/api_integration_test.dart`:** +```dart +import 'package:flutter_test/flutter_test.dart'; +import 'package:integration_test/integration_test.dart'; +import 'package:your_app/services/api_client.dart'; +import 'package:your_app/services/health_service.dart'; + +void main() { + IntegrationTestWidgetsFlutterBinding.ensureInitialized(); + + group('API Integration Tests', () { + late ApiClient apiClient; + late HealthService healthService; + + setUp(() { + apiClient = ApiClient(); + healthService = HealthService(apiClient); + }); + + testWidgets('Health check endpoint works', (tester) async { + // Ensure backend is running on localhost:5246 + final result = await healthService.checkHealth(); + + expect(result.isSuccess, true); + expect(result.data, true); + }); + }); +} +``` + +### Run Tests + +```bash +# Unit tests +flutter test + +# Integration tests (requires backend running) +flutter test integration_test/ +``` + +--- + +## Step 10: Error Handling & User Feedback + +### Create Error Display Widget + +**`lib/widgets/error_snackbar.dart`:** +```dart +import 'package:flutter/material.dart'; +import '../models/api_result.dart'; + +class ErrorSnackbar { + static void show(BuildContext context, ApiResult result) { + if (result.isFailure) { + ScaffoldMessenger.of(context).showSnackBar( + SnackBar( + content: Text(result.errorMessage ?? 'An error occurred'), + backgroundColor: Colors.red, + action: SnackBarAction( + label: 'Dismiss', + textColor: Colors.white, + onPressed: () { + ScaffoldMessenger.of(context).hideCurrentSnackBar(); + }, + ), + ), + ); + } + } + + static void showValidationErrors( + BuildContext context, + Map>? errors, + ) { + if (errors == null || errors.isEmpty) return; + + final errorMessages = errors.entries + .map((e) => '${e.key}: ${e.value.join(', ')}') + .join('\n'); + + ScaffoldMessenger.of(context).showSnackBar( + SnackBar( + content: Text(errorMessages), + backgroundColor: Colors.orange, + duration: const Duration(seconds: 5), + ), + ); + } +} +``` + +--- + +## Step 11: Monitoring API Changes + +### Create Update Script + +**`scripts/update_api_client.sh`:** +```bash +#!/bin/bash + +echo "Updating API client from backend..." + +# Pull latest backend changes +cd ../backend +git pull origin main + +# Regenerate Dart client +cd ../flutter-app +openapi-generator-cli generate \ + -i ../backend/docs/openapi.json \ + -g dart \ + -o lib/api/generated \ + --additional-properties=pubName=codex_api_client,pubLibrary=codex_api_client + +echo "API client updated!" +echo "" +echo "Next steps:" +echo "1. Check backend/docs/CHANGELOG.md for breaking changes" +echo "2. Run: flutter pub get" +echo "3. Run: flutter test" +echo "4. Fix any compilation errors" +``` + +Make executable: +```bash +chmod +x scripts/update_api_client.sh +``` + +--- + +## Step 12: CI/CD Integration + +### GitHub Actions Workflow + +**`.github/workflows/flutter_ci.yml`:** +```yaml +name: Flutter CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout Flutter app + uses: actions/checkout@v3 + + - name: Checkout backend + uses: actions/checkout@v3 + with: + repository: your-org/backend + path: backend + + - name: Setup Flutter + uses: subosito/flutter-action@v2 + with: + flutter-version: '3.16.0' + channel: 'stable' + + - name: Install OpenAPI Generator + run: npm install -g @openapitools/openapi-generator-cli + + - name: Check for API changes + run: | + if ! diff -q lib/api/openapi.json backend/docs/openapi.json; then + echo "API changes detected!" + ./scripts/update_api_client.sh + fi + + - name: Get dependencies + run: flutter pub get + + - name: Analyze code + run: flutter analyze + + - name: Run tests + run: flutter test + + - name: Build app + run: flutter build apk --debug +``` + +--- + +## Complete Checklist for Flutter Team + +### Initial Setup +- [ ] Clone backend repository or access `docs/openapi.json` +- [ ] Review `docs/CHANGELOG.md` for breaking changes +- [ ] Review `docs/ARCHITECTURE.md` for CQRS patterns +- [ ] Install OpenAPI Generator CLI +- [ ] Generate Dart API client +- [ ] Update `pubspec.yaml` with dependencies +- [ ] Run `flutter pub get` +- [ ] Create environment configuration files +- [ ] Setup API client with interceptors + +### Service Layer +- [ ] Create `ApiClient` with authentication +- [ ] Create `ApiResult` model for error handling +- [ ] Create service classes (Health, User, etc.) +- [ ] Setup Riverpod providers +- [ ] Implement error handling + +### Testing +- [ ] Write unit tests for services +- [ ] Write widget tests for UI +- [ ] Setup integration tests +- [ ] Test authentication flow +- [ ] Test error scenarios (401, 400, 500) + +### UI Integration +- [ ] Create error display widgets +- [ ] Implement loading states +- [ ] Add API health indicator +- [ ] Handle validation errors in forms + +### DevOps +- [ ] Create API update script +- [ ] Setup CI/CD pipeline +- [ ] Configure environment variables +- [ ] Document team workflow + +--- + +## Common Issues & Solutions + +### Issue: "Failed to load .env file" +**Solution:** Ensure `.env` file exists and is listed in `pubspec.yaml` assets. + +### Issue: "401 Unauthorized on all requests" +**Solution:** Check that `ApiClient` is properly adding Bearer token to headers. + +### Issue: "Connection refused to localhost" +**Solution:** +- On Android emulator: use `http://10.0.2.2:5246` +- On iOS simulator: use `http://localhost:5246` +- Update `API_BASE_URL` in `.env` accordingly + +### Issue: "Type errors after regenerating client" +**Solution:** Breaking changes occurred. Review `backend/docs/CHANGELOG.md` and update service layer. + +### Issue: "OpenAPI generator fails" +**Solution:** Ensure `openapi.json` is valid JSON. Validate with: `cat openapi.json | python3 -m json.tool` + +--- + +## Android Network Configuration + +**`android/app/src/main/AndroidManifest.xml`:** +```xml + + + + + + + +``` + +--- + +## iOS Network Configuration + +**`ios/Runner/Info.plist`:** +```xml +NSAppTransportSecurity + + NSAllowsArbitraryLoads + + +``` + +--- + +## Support & Resources + +- **OpenAPI Spec:** `backend/docs/openapi.json` +- **Breaking Changes:** `backend/docs/CHANGELOG.md` +- **Architecture:** `backend/docs/ARCHITECTURE.md` +- **Backend API (Dev):** `http://localhost:5246` +- **Swagger UI (Dev):** `http://localhost:5246/swagger` + +--- + +**Last Updated:** 2025-01-26 +**Backend API Version:** v1 +**OpenAPI Version:** 3.0.1 +**Recommended Dart Client Generator:** openapi-generator-cli with `dart` generator diff --git a/BACKEND/.claude-docs/FLUTTER-QUICK-START.md b/BACKEND/.claude-docs/FLUTTER-QUICK-START.md new file mode 100644 index 0000000..4f6628e --- /dev/null +++ b/BACKEND/.claude-docs/FLUTTER-QUICK-START.md @@ -0,0 +1,142 @@ +# 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 +# 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 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 + + +``` + +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` diff --git a/BACKEND/.claude-docs/README.md b/BACKEND/.claude-docs/README.md new file mode 100644 index 0000000..08f6c33 --- /dev/null +++ b/BACKEND/.claude-docs/README.md @@ -0,0 +1,45 @@ +# Claude Code Context & Guidelines + +This directory contains context and guidelines for Claude Code when working with this repository. + +## File Organization + +### Core Guidelines +- **[strict-typing.md](strict-typing.md)** - Strict typing requirements (NO dynamic, NO var, NO object) +- **[api-quick-reference.md](api-quick-reference.md)** - Quick API reference + +### Frontend Integration (Flutter) +- **[FLUTTER-QUICK-START.md](FLUTTER-QUICK-START.md)** - Flutter 5-minute quick start guide +- **[FLUTTER-INTEGRATION.md](FLUTTER-INTEGRATION.md)** - Complete Flutter integration documentation + +## Quick Reference + +### For Claude Code +When working on this project, always refer to: +1. `/CLAUDE.md` - Main project standards and CQRS patterns +2. `.claude-docs/strict-typing.md` - Type safety requirements + +### For Developers +See project root: +- `/README.md` - Main project documentation +- `/CLAUDE.md` - Claude Code instructions and CQRS patterns +- `/docs/` - API documentation, architecture, and OpenAPI spec + +### For Flutter Team +- Start: `.claude-docs/FLUTTER-QUICK-START.md` +- Complete guide: `.claude-docs/FLUTTER-INTEGRATION.md` +- API contract: `/docs/openapi.json` + +## Document Purpose + +These files provide context to Claude Code to ensure: +- Consistent code quality +- Proper typing and safety +- Clear communication +- Successful frontend integration with Flutter + +--- + +**Note**: This directory is for Claude Code context. For general project documentation, see the root `/docs` directory. + +**Last Updated**: 2025-01-26 diff --git a/BACKEND/.claude-docs/api-quick-reference.md b/BACKEND/.claude-docs/api-quick-reference.md new file mode 100644 index 0000000..0652894 --- /dev/null +++ b/BACKEND/.claude-docs/api-quick-reference.md @@ -0,0 +1,188 @@ +# API Quick Reference + +Quick reference for common API integration tasks. See [api-contract.md](api-contract.md) for complete documentation. + +**Status:** **No Authentication Required** (R&D Phase) + +--- + +## Connection + +``` +Base URL (Development): http://localhost:5246 +Swagger UI: http://localhost:5246/swagger +CORS Allowed Origins: + - http://localhost:3000 + - http://localhost:54952 + - http://localhost:62000 +``` + +--- + +## Endpoint Patterns + +| Type | Pattern | Method | Purpose | +|------|---------|--------|---------| +| Query | `/api/query/{name}` | POST/GET | Single value queries | +| Dynamic Query | `/api/dynamicquery/{typename}` | POST | Paginated queries | +| Command | `/api/command/{name}` | POST | Write operations | + +**Naming**: `HealthQuery` → `/api/query/health` (suffix removed, lowercased) + +--- + +## Dynamic Query Request + +```json +{ + "page": 1, + "pageSize": 20, + "filters": [ + { + "path": "propertyName", + "type": "Equal", + "value": "searchValue" + } + ], + "sorts": [ + { + "path": "propertyName", + "ascending": true + } + ] +} +``` + +**Critical**: Use `path` (not `field`), `type` (not `operator`), `ascending` boolean (not `direction` string) + +--- + +## Dynamic Query Response + +```json +{ + "data": [...], + "totalRecords": 100, + "aggregates": [] +} +``` + +**Critical**: Use `totalRecords` (not `totalItems`). Calculate `totalPages` yourself. + +--- + +## Filter Types + +`Equal`, `NotEqual`, `Contains`, `StartsWith`, `EndsWith`, `GreaterThan`, `GreaterThanOrEqual`, `LessThan`, `LessThanOrEqual`, `In` + +**Case-sensitive**: Use exact capitalization (e.g., `Equal` not `equal`) + +--- + +## Validation Error (400) + +```json +{ + "status": 400, + "title": "One or more validation errors occurred.", + "errors": { + "fieldName": ["Error message 1", "Error message 2"] + }, + "traceId": "00-abc123-def456-00" +} +``` + +**Critical**: `errors` contains field-specific arrays of error messages + +--- + +## Common Mistakes to Avoid + +**Wrong**: `/api/query/userlist` for paginated queries +**Right**: `/api/dynamicquery/userlist` + +**Wrong**: `{ "field": "name", "operator": "Contains" }` +**Right**: `{ "path": "name", "type": "Contains" }` + +**Wrong**: `{ "field": "name", "direction": "Ascending" }` +**Right**: `{ "path": "name", "ascending": true }` + +**Wrong**: Reading `response.totalItems` +**Right**: Reading `response.totalRecords` + +**Wrong**: Frontend on port 3000 or 5173 +**Right**: Frontend on port 54952 (for CORS) + +--- + +## TypeScript Types + +```typescript +interface DynamicQueryCriteria { + page?: number; + pageSize?: number; + filters?: Array<{ + path: string; + type: 'Equal' | 'NotEqual' | 'Contains' | 'StartsWith' | 'EndsWith' | + 'GreaterThan' | 'GreaterThanOrEqual' | 'LessThan' | 'LessThanOrEqual' | 'In'; + value: unknown; + }>; + sorts?: Array<{ + path: string; + ascending: boolean; + }>; +} + +interface DynamicQueryResponse { + data: T[]; + totalRecords: number; + aggregates: unknown[]; +} +``` + +--- + +## Dart Types + +```dart +class DynamicQueryCriteria { + final int? page; + final int? pageSize; + final List? filters; + final List? sorts; +} + +class Filter { + final String path; + final FilterType type; // enum: equal, contains, etc. + final dynamic value; +} + +class Sort { + final String path; + final bool ascending; +} + +class DynamicQueryResponse { + final List data; + final int totalRecords; + final List aggregates; +} +``` + +--- + +## Testing + +```bash +# Health check +curl -X POST http://localhost:5246/api/query/health \ + -H "Content-Type: application/json" \ + -d "{}" + +# Expected response: true +``` + +--- + +For complete documentation, examples, and error handling, see [frontend-api-integration.md](frontend-api-integration.md). diff --git a/BACKEND/.claude-docs/strict-typing.md b/BACKEND/.claude-docs/strict-typing.md new file mode 100644 index 0000000..3b976dd --- /dev/null +++ b/BACKEND/.claude-docs/strict-typing.md @@ -0,0 +1,41 @@ +# Strict Typing - NO EXCEPTIONS + +**Claude must ALWAYS use explicit types in ALL code. The use of `any` type is FORBIDDEN.** + +## Rules: +1. **Every variable must have an explicit type annotation** +2. **Every function parameter must be typed** +3. **Every function return value must be typed** +4. **Never use `any`, `dynamic` (in Dart), or equivalent loose types** +5. **Use proper generics, interfaces, and type unions instead** + +## Examples: + +**FORBIDDEN:** +```typescript +const data: any = fetchData(); +function process(input: any): any { ... } +``` + +```dart +dynamic value = getValue(); +void handleData(var data) { ... } +``` + +**REQUIRED:** +```typescript +const data: UserData = fetchData(); +function process(input: UserInput): ProcessedOutput { ... } +``` + +```dart +UserData value = getValue(); +void handleData(RequestData data) { ... } +``` + +**This rule applies to:** +- TypeScript/JavaScript +- Dart/Flutter +- Python (use type hints) +- All statically-typed languages +- Even when interfacing with external APIs - create proper type definitions diff --git a/BACKEND/.claude/skills/backend-devops-expert/SKILL.md b/BACKEND/.claude/skills/backend-devops-expert/SKILL.md new file mode 100644 index 0000000..b12eea8 --- /dev/null +++ b/BACKEND/.claude/skills/backend-devops-expert/SKILL.md @@ -0,0 +1,427 @@ +# Backend/DevOps Expert Planner + +## Purpose + +This skill transforms Claude into an expert backend and DevOps planner specialized in: +- ASP.NET Core 8.0 API design with CQRS patterns +- PostgreSQL database architecture and migrations +- Containerization with Docker +- CI/CD pipelines with GitHub Actions +- Infrastructure as Code (Terraform/Azure) +- Security, monitoring, and deployment strategies + +## When to Use This Skill + +Use this skill when you need to: +- Plan a new backend feature or microservice +- Design database schema and migrations +- Setup CI/CD pipelines +- Containerize applications +- Plan infrastructure deployment +- Design security, monitoring, or logging solutions +- Architect API integrations + +## Planning Methodology + +### Phase 1: Discovery and Context Gathering + +Before creating any plan, Claude MUST: + +1. **Read Project Documentation**: + - `CLAUDE.md` - Project standards and CQRS patterns + - `.claude-docs/strict-typing.md` - Typing requirements + - `docs/ARCHITECTURE.md` - System architecture + - `docs/CHANGELOG.md` - Breaking changes history + - `README.md` - Project overview + +2. **Understand Current State**: + - Examine `.csproj` files for dependencies and versions + - Review `appsettings.json` for configuration patterns + - Check existing Commands/Queries patterns + - Identify database entities and DbContext structure + - Review existing scripts (e.g., `export-openapi.sh`) + +3. **Identify Constraints**: + - .NET version policy (currently .NET 8.0 LTS - NO upgrades) + - Existing architectural patterns (CQRS, Module system) + - Framework constraints (OpenHarbor.CQRS, PoweredSoft modules) + - Database type (PostgreSQL) + - Deployment environment (Development vs Production) + +### Phase 2: Test-First Planning + +For every feature or infrastructure change, plan tests FIRST: + +1. **Unit Tests**: + ```csharp + // Plan xUnit tests for handlers + public class MyCommandHandlerTests + { + [Fact] + public async Task HandleAsync_ValidInput_ReturnsSuccess() + { + // Arrange, Act, Assert + } + } + ``` + +2. **Integration Tests**: + ```csharp + // Plan integration tests with TestContainers + public class MyApiIntegrationTests : IAsyncLifetime + { + private readonly PostgreSqlContainer _postgres; + + [Fact] + public async Task Endpoint_ValidRequest_Returns200() + { + // Test actual HTTP endpoint + } + } + ``` + +3. **API Contract Tests**: + ```bash + # Validate OpenAPI spec matches implementation + dotnet build + ./export-openapi.sh + # Compare docs/openapi.json with expected schema + ``` + +### Phase 3: Implementation Planning + +Create a detailed, step-by-step plan with: + +#### A. Prerequisites Check +```markdown +- [ ] .NET 8.0 SDK installed +- [ ] PostgreSQL 15+ running +- [ ] Docker Desktop installed (if containerizing) +- [ ] Git repository initialized +- [ ] Required NuGet packages documented +``` + +#### B. Explicit Commands +Use project-specific libraries and exact commands: + +```bash +# Add NuGet packages +dotnet add Codex.Api/Codex.Api.csproj package OpenHarbor.CQRS.AspNetCore --version 8.1.0-rc1 +dotnet add Codex.CQRS/Codex.CQRS.csproj package FluentValidation --version 11.3.1 + +# Create migration +dotnet ef migrations add AddUserEntity --project Codex.Dal + +# Update database +dotnet ef database update --project Codex.Dal + +# Export OpenAPI spec +dotnet build +./export-openapi.sh +``` + +#### C. File-by-File Implementation + +For each file, provide: +1. **Full file path**: `Codex.CQRS/Commands/CreateUserCommand.cs` +2. **Complete code**: No placeholders, full implementation +3. **XML documentation**: For OpenAPI generation +4. **Module registration**: Where and how to register services + +Example: +```markdown +### Step 3: Create CreateUserCommand + +**File**: `Codex.CQRS/Commands/CreateUserCommand.cs` + +**Code**: +```csharp +using FluentValidation; +using OpenHarbor.CQRS.Abstractions; +using Codex.Dal; +using Codex.Dal.Entities; + +namespace Codex.CQRS.Commands; + +///

+/// Creates a new user account +///

+public record CreateUserCommand +{ + ///

Unique username

+ public string Username { get; init; } = string.Empty; + + ///

Email address

+ public string Email { get; init; } = string.Empty; +} + +public class CreateUserCommandHandler(CodexDbContext dbContext) + : ICommandHandler +{ + public async Task HandleAsync(CreateUserCommand command, CancellationToken cancellationToken = default) + { + var user = new User + { + Username = command.Username, + Email = command.Email, + CreatedAt = DateTime.UtcNow + }; + + dbContext.Users.Add(user); + await dbContext.SaveChangesAsync(cancellationToken); + } +} + +public class CreateUserCommandValidator : AbstractValidator +{ + public CreateUserCommandValidator() + { + RuleFor(x => x.Username) + .NotEmpty().WithMessage("Username is required") + .MinimumLength(3).WithMessage("Username must be at least 3 characters"); + + RuleFor(x => x.Email) + .NotEmpty().WithMessage("Email is required") + .EmailAddress().WithMessage("Invalid email format"); + } +} +``` + +**Registration**: In `Codex.CQRS/CommandsModule.cs`: +```csharp +services.AddCommand(); +``` + +**Test**: Create `Codex.Tests/Commands/CreateUserCommandTests.cs` (see test plan above) +``` + +#### D. Success Criteria + +For each step, define clear success criteria: + +```markdown +### Success Criteria for Step 3: + +- [ ] Command file compiles without errors +- [ ] Validator tests pass with valid and invalid inputs +- [ ] Integration test creates user in database +- [ ] OpenAPI spec includes `/api/command/createuser` endpoint +- [ ] XML documentation appears in Swagger UI +- [ ] CHANGELOG.md updated if breaking change +- [ ] Code follows strict typing rules (no `dynamic`, explicit types) +``` + +### Phase 4: DevOps and Deployment Planning + +When planning infrastructure: + +#### A. Containerization +```dockerfile +# Use templates/Dockerfile.net8 as base +# Customize for specific project needs +# Include multi-stage build +# Optimize layer caching +``` + +#### B. CI/CD Pipeline +```yaml +# Use templates/github-actions.yml as base +# Add project-specific steps: +# 1. dotnet restore +# 2. dotnet build +# 3. dotnet test +# 4. ./export-openapi.sh +# 5. Validate docs/openapi.json hasn't broken +# 6. Docker build and push +# 7. Deploy to staging +``` + +#### C. Infrastructure as Code +```terraform +# Use templates/terraform-azure.tf as base +# Plan resources: +# - Azure App Service (Linux, .NET 8.0) +# - Azure Database for PostgreSQL +# - Azure Container Registry +# - Application Insights +# - Key Vault for secrets +``` + +### Phase 5: Security and Monitoring + +Every plan must include: + +1. **Security Checklist** (see `references/security-checklist.md`): + - [ ] HTTPS enforced in production + - [ ] CORS properly configured + - [ ] SQL injection prevention (EF Core parameterized queries) + - [ ] Input validation with FluentValidation + - [ ] Authentication/Authorization strategy + - [ ] Secrets in environment variables or Key Vault + +2. **Monitoring and Logging**: + - [ ] Structured logging with Serilog + - [ ] Health check endpoints + - [ ] Application Insights integration + - [ ] Error tracking and alerting + - [ ] Performance metrics + +3. **Database Backup Strategy**: + - [ ] Automated PostgreSQL backups + - [ ] Point-in-time recovery plan + - [ ] Migration rollback procedures + +## Plan Output Format + +### Plan Structure + +```markdown +# [Feature/Task Name] + +## Overview +[Brief description of what we're building/deploying] + +## Prerequisites +- [ ] Requirement 1 +- [ ] Requirement 2 + +## Test Plan (Write Tests First) +### Unit Tests +[Test file paths and test cases] + +### Integration Tests +[Integration test scenarios] + +### API Contract Tests +[OpenAPI validation steps] + +## Implementation Steps + +### Step 1: [Task Name] +**Objective**: [What this step accomplishes] + +**Commands**: +```bash +[Exact commands to run] +``` + +**Files to Create/Modify**: +- `path/to/file.cs`: [Description] + +**Code**: +```csharp +[Complete implementation] +``` + +**Success Criteria**: +- [ ] Criterion 1 +- [ ] Criterion 2 + +**Verification**: +```bash +[Commands to verify success] +``` + +[Repeat for each step] + +## DevOps Tasks + +### Containerization +[Docker setup if needed] + +### CI/CD Pipeline +[GitHub Actions workflow] + +### Infrastructure +[Terraform/Azure setup] + +## Security Checklist +- [ ] Security item 1 +- [ ] Security item 2 + +## Monitoring and Logging +- [ ] Logging configured +- [ ] Health checks implemented +- [ ] Metrics collected + +## Post-Deployment Verification +```bash +[Commands to verify deployment] +``` + +## Documentation Updates +- [ ] Update CHANGELOG.md (if breaking changes) +- [ ] Update README.md (if new features) +- [ ] Export OpenAPI spec: `./export-openapi.sh` +- [ ] Notify frontend team of API changes + +## Rollback Plan +[Steps to rollback if issues occur] +``` + +## Reference Materials + +This skill includes comprehensive reference materials in the `references/` directory: + +1. **cqrs-patterns.md**: OpenHarbor.CQRS patterns specific to this project +2. **dotnet-architecture.md**: .NET 8.0 best practices and module patterns +3. **postgresql-migrations.md**: EF Core migration strategies +4. **docker-deployment.md**: Container best practices for .NET 8.0 +5. **cicd-pipelines.md**: GitHub Actions templates and patterns +6. **security-checklist.md**: Security requirements for APIs +7. **templates/**: Reusable code and configuration templates + +## Key Principles + +1. **Never Assume Context**: Always read project documentation first +2. **Test-First**: Plan tests before implementation +3. **Explicit Commands**: Use exact commands with project-specific libraries +4. **Clear Success Criteria**: Define measurable success for each step +5. **Reference Project Docs**: Link to CLAUDE.md, docs/, .claude-docs/ +6. **Follow Project Standards**: Respect .NET version policy, typing rules +7. **No Placeholders**: Provide complete, working code +8. **Security by Default**: Include security considerations in every plan +9. **Idempotent Operations**: Ensure operations can be safely repeated +10. **Document Everything**: Update docs and notify stakeholders + +## Example Usage + +**User**: "Plan a new feature to add user authentication with JWT tokens" + +**Claude with Skill**: +1. Reads CLAUDE.md, ARCHITECTURE.md, current codebase +2. Identifies current state (no auth implemented) +3. Plans unit tests for token generation/validation +4. Plans integration tests for protected endpoints +5. Creates step-by-step implementation: + - Add JWT NuGet packages + - Create JwtService + - Add authentication middleware to Program.cs + - Create LoginCommand with validator + - Update OpenAPI spec with Bearer scheme + - Add [Authorize] attributes to protected commands/queries + - Create Dockerfile with secret management + - Update GitHub Actions to test auth flows +6. Includes security checklist +7. Plans monitoring for failed auth attempts +8. Provides rollback plan + +## Skill Activation + +When this skill is activated, Claude will: +1. Immediately read project documentation +2. Ask clarifying questions about requirements +3. Create a comprehensive plan following the methodology above +4. Present the plan for user approval before execution +5. Track progress using todo lists +6. Verify success criteria after each step + +## Notes + +- This skill is for **planning**, not execution (unless user approves) +- Always use the project's actual file paths, packages, and patterns +- Respect the project's .NET 8.0 LTS policy +- Follow strict typing rules +- Reference templates but customize for specific needs +- Keep plans detailed but concise +- Include verification steps throughout diff --git a/BACKEND/.config/dotnet-tools.json b/BACKEND/.config/dotnet-tools.json new file mode 100644 index 0000000..c347b13 --- /dev/null +++ b/BACKEND/.config/dotnet-tools.json @@ -0,0 +1,13 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "roslynator.dotnet.cli": { + "version": "0.11.0", + "commands": [ + "roslynator" + ], + "rollForward": false + } + } +} \ No newline at end of file diff --git a/BACKEND/.gitignore b/BACKEND/.gitignore new file mode 100644 index 0000000..cf919f0 --- /dev/null +++ b/BACKEND/.gitignore @@ -0,0 +1,47 @@ +# Build results +[Dd]ebug/ +[Dd]ebugPublic/ +[Rr]elease/ +[Rr]eleases/ +x64/ +x86/ +[Aa][Rr][Mm]/ +[Aa][Rr][Mm]64/ +bld/ +[Bb]in/ +[Oo]bj/ +[Ll]og/ +[Ll]ogs/ + +# Visual Studio files +.vs/ +.vscode/ + +# JetBrains Rider +.idea/ +*.sln.iml +*.user +*.userosscache +*.suo +*.user +*.sln.docstates + +# User-specific files +*.rsuser +*.suo +*.user +*.userosscache +*.sln.docstates + +# Temporary files +COMMIT_MESSAGE.txt +READY_FOR_COMMIT.txt + +# OS files +.DS_Store +Thumbs.db + +# Code review results +code-review-results.xml +.sonarqube/ +CODE-REVIEW-SUMMARY.md diff --git a/BACKEND/CLAUDE.md b/BACKEND/CLAUDE.md new file mode 100644 index 0000000..e84918e --- /dev/null +++ b/BACKEND/CLAUDE.md @@ -0,0 +1,182 @@ +You are the Devops/Backend CTO, the Frontend/UI/UX/Branding CTO reports to you. you two work in a perfectly coordinated duo. + +# CODEX_ADK Backend - AI Context + +## Project +Multi-agent AI laboratory for building, testing sovereign AI agents with hierarchical workflows. CQRS-based ASP.NET Core 8.0 Web API serving Flutter app via REST API. + +## Stack +- .NET 8 LTS, OpenHarbor.CQRS, PostgreSQL 15, EF Core 8 +- FluentValidation, PoweredSoft modules, AES-256 encryption +- Docker Compose (postgres + ollama containers) + +## .NET Version Policy +**CRITICAL**: This project uses .NET 8.0 LTS. Do NOT upgrade to .NET 9+ without explicit approval. All projects target `net8.0`. + +## Architecture +``` +Codex.Api/ # API endpoints, Program.cs, AppModule +Codex.CQRS/ # Commands, Queries, Handlers +Codex.Dal/ # DbContext, Entities, Migrations +``` + +### CQRS Pattern +- **Commands**: Write operations (create/update/delete). Persist data, execute business logic. +- **Queries**: Read operations. Always use `.AsNoTracking()` for read-only queries. + +### Module System +PoweredSoft `IModule` system organizes features: +1. Create feature modules (CommandsModule, QueriesModule, DalModule) +2. Register in `AppModule` +3. Register `AppModule` in `Program.cs`: `services.AddModule()` + +**Pattern Details**: See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) + +## Entities +- **Agents**: Id, Name, Provider (OpenAI/Anthropic/Ollama), Model, ApiKey(encrypted), SystemPrompt, Temperature, MaxTokens +- **AgentTools**: Id, AgentId, Name, Description, Parameters(JSON), IsEnabled +- **Conversations**: Id, AgentId, Title, StartedAt, EndedAt, Context(JSON) +- **ConversationMessages**: Id, ConversationId, Role, Content, TokenCount, Timestamp +- **AgentExecutions**: Id, AgentId, ConversationId, Status, StartedAt, CompletedAt, Result, Error, TokensUsed, Cost + +## Commands & Queries + +### Commands (POST /api/command/{name}) +- CreateAgent, UpdateAgent, DeleteAgent → `ICommand` +- CreateConversation → `ICommand` +- StartAgentExecution, CompleteAgentExecution → `ICommand` + +**Structure**: 3-part pattern (Command record, Handler, Validator) in single file. +```csharp +public record MyCommand { /* properties */ } +public class MyCommandHandler(DbContext db) : ICommandHandler { } +public class MyCommandValidator : AbstractValidator { } +// Registration: services.AddCommand(); +``` + +### Queries (GET/POST /api/query/{name}) +- Health → `bool` +- GetAgent, GetAgentExecution, GetConversation → DTOs +- Paginated: Use `IQueryableProviderOverride` for dynamic filtering/sorting + +**Single Value**: `IQueryHandler` +**Paginated**: `IQueryableProviderOverride` with `.AsNoTracking()` + +**Complete API Reference**: See [.claude-docs/api-quick-reference.md](.claude-docs/api-quick-reference.md) + +## Docker Setup + +```bash +# Start services (PostgreSQL + Ollama) +docker-compose up -d + +# Apply migrations +dotnet ef database update --project Codex.Dal --connection "Host=localhost;Database=codex;Username=postgres;Password=postgres" + +# Stop services +docker-compose down + +# Reset database (CAUTION: deletes all data) +docker-compose down -v && docker-compose up -d +dotnet ef database update --project Codex.Dal --connection "Host=localhost;Database=codex;Username=postgres;Password=postgres" + +# Ollama model management +docker exec codex-ollama ollama pull phi +docker exec codex-ollama ollama list +``` + +**Services**: PostgreSQL (localhost:5432), Ollama (localhost:11434) + +**Conflict**: Stop local PostgreSQL first: `brew services stop postgresql@14` + +## Building & Running + +```bash +# Build +dotnet build + +# Run API (HTTP: 5246, HTTPS: 7108, Swagger: /swagger) +dotnet run --project Codex.Api/Codex.Api.csproj + +# Migrations +dotnet ef migrations add --project Codex.Dal +dotnet ef database update --project Codex.Dal + +# Export OpenAPI spec (after API changes) +dotnet build && ./export-openapi.sh +``` + +## Required Service Registration (Program.cs) + +```csharp +// PoweredSoft & CQRS +builder.Services.AddPoweredSoftDataServices(); +builder.Services.AddPoweredSoftEntityFrameworkCoreDataServices(); +builder.Services.AddPoweredSoftDynamicQuery(); +builder.Services.AddDefaultCommandDiscovery(); +builder.Services.AddDefaultQueryDiscovery(); +builder.Services.AddFluentValidation(); +builder.Services.AddModule(); + +// Controllers (required for OpenHarbor CQRS) +var mvcBuilder = builder.Services.AddControllers() + .AddJsonOptions(o => o.JsonSerializerOptions.Converters.Insert(0, new JsonStringEnumConverter())); + +mvcBuilder.AddOpenHarborCommands(); +mvcBuilder.AddOpenHarborQueries().AddOpenHarborDynamicQueries(); +``` + +## Key Dependencies +- OpenHarbor.CQRS (core + AspNetCore.Mvc + DynamicQuery.AspNetCore + FluentValidation) +- PoweredSoft.Module.Abstractions + Data.EntityFrameworkCore + DynamicQuery +- FluentValidation.AspNetCore + +## Development Guidelines + +1. **Query Performance**: Always `.AsNoTracking()` for read-only queries +2. **File Organization**: Command/Handler/Validator in single file +3. **Validation**: All commands require validators (even if empty) +4. **Modules**: Group related commands/queries by feature +5. **XML Documentation**: Add XML comments for OpenAPI generation +6. **OpenAPI Export**: Run `./export-openapi.sh` after API changes +7. **CORS**: Configure allowed origins in appsettings per environment +8. **HTTPS**: Only enforced in non-development environments + +## Known Issues +- Dynamic queries not in OpenAPI spec (OpenHarbor limitation) +- Hardcoded secrets in appsettings.json (CRITICAL - fix before production) +- Manual endpoint registration needed for Swagger + +## Current Focus +Replace dynamic queries with simple GET endpoints for MVP. Fix security before production. + +--- + +# MANDATORY CODING STANDARDS + +## Code Style - NO EXCEPTIONS +**CRITICAL**: NEVER use emojis in code, comments, commit messages, or any project files. All communication must be professional and emoji-free. + +## Git Commit Standards +**CRITICAL**: All commits MUST follow this authorship format: +- **Author**: Svrnty +- **Co-Author**: Jean-Philippe Brule + +When creating commits, always include: +``` +Co-Authored-By: Jean-Philippe Brule +``` + +## Strict Typing - NO EXCEPTIONS +See [.claude-docs/strict-typing.md](.claude-docs/strict-typing.md) for complete typing requirements. + +## Frontend Integration +See [.claude-docs/frontend-api-integration.md](.claude-docs/frontend-api-integration.md) for complete API integration specifications for frontend teams. + +--- + +**Additional Documentation**: +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Detailed system architecture +- [docs/COMPLETE-API-REFERENCE.md](docs/COMPLETE-API-REFERENCE.md) - Full API contract with examples +- [docs/CHANGELOG.md](docs/CHANGELOG.md) - Breaking changes history +- [.claude-docs/FLUTTER-QUICK-START.md](.claude-docs/FLUTTER-QUICK-START.md) - Flutter integration guide diff --git a/BACKEND/Codex.Api/AppModule.cs b/BACKEND/Codex.Api/AppModule.cs new file mode 100644 index 0000000..9873ff7 --- /dev/null +++ b/BACKEND/Codex.Api/AppModule.cs @@ -0,0 +1,18 @@ +using Codex.CQRS; +using Codex.Dal; +using OpenHarbor.CQRS.DynamicQuery.Abstractions; +using PoweredSoft.Module.Abstractions; + +namespace Codex.Api; + +public class AppModule : IModule +{ + public IServiceCollection ConfigureServices(IServiceCollection services) + { + services.AddModule(); + services.AddModule(); + services.AddModule(); + + return services; + } +} diff --git a/BACKEND/Codex.Api/Codex.Api.csproj b/BACKEND/Codex.Api/Codex.Api.csproj new file mode 100644 index 0000000..b3bdc7e --- /dev/null +++ b/BACKEND/Codex.Api/Codex.Api.csproj @@ -0,0 +1,35 @@ + + + + net8.0 + enable + enable + true + $(NoWarn);1591 + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/BACKEND/Codex.Api/Endpoints/ManualEndpointRegistration.cs b/BACKEND/Codex.Api/Endpoints/ManualEndpointRegistration.cs new file mode 100644 index 0000000..483954b --- /dev/null +++ b/BACKEND/Codex.Api/Endpoints/ManualEndpointRegistration.cs @@ -0,0 +1,241 @@ +using Codex.CQRS.Commands; +using Codex.CQRS.Queries; +using Codex.Dal.QueryProviders; +using Microsoft.AspNetCore.Mvc; +using Microsoft.OpenApi.Models; +using OpenHarbor.CQRS.Abstractions; +using OpenHarbor.CQRS.DynamicQuery.Abstractions; +using PoweredSoft.Data.Core; +using PoweredSoft.DynamicQuery; +using PoweredSoft.DynamicQuery.Core; + +namespace Codex.Api.Endpoints; + +///

+/// Manual endpoint registration for endpoints requiring custom OpenAPI documentation. +/// OpenHarbor.CQRS v8.1.0-rc1 auto-registers and auto-documents all ICommandHandler implementations. +/// Manual registration should only be used for advanced customization needs. +///

+public static class ManualEndpointRegistration +{ + public static WebApplication MapCodexEndpoints(this WebApplication app) + { + // ============================================================ + // COMMANDS - AUTO-REGISTERED BY OPENHARBOR.CQRS + // ============================================================ + // All commands are automatically registered and documented by the framework: + // - CreateAgent (no return value) + // - UpdateAgent (no return value) + // - DeleteAgent (no return value) + // - CreateConversation (returns Guid) + // - StartAgentExecution (returns Guid) + // - CompleteAgentExecution (no return value) + // + // Routes: POST /api/command/{commandName} + // Documentation: Automatically generated from XML comments in command classes + + // ============================================================ + // QUERIES - AUTO-REGISTERED BY OPENHARBOR.CQRS + // ============================================================ + // All queries are automatically registered and documented by the framework: + // - Health (simple check) + // - GetAgent (returns AgentDetails) + // - GetAgentExecution (returns AgentExecutionDetails) + // - GetConversation (returns ConversationDetails) + // + // Routes: POST /api/query/{queryName} + // Documentation: Automatically generated from XML comments in query classes + + // ============================================================ + // DYNAMIC QUERIES (Paginated Lists) + // ============================================================ + // NOTE: Dynamic queries are auto-registered by OpenHarbor but not auto-documented. + // They work via /api/dynamicquery/{ItemType} but aren't in Swagger without manual registration. + // The endpoints exist and function - frontend can use them directly from openapi.json examples below. + + // Manual registration disabled for now - OpenHarbor handles these automatically + // TODO: Add proper schema documentation for dynamic query request/response + + /* + // ListAgents + app.MapPost("/api/dynamicquery/ListAgentsQueryItem", + async (HttpContext context, + IQueryableProvider provider, + IAsyncQueryableService queryService) => + { + var query = await context.Request.ReadFromJsonAsync