Feat/api integration and docs

[vollereiseelee]

PR Type

Enhancement, Documentation

---

Description

• Integrated frontend with API Gateway for all services

  • Updated frontend API base URLs to use API Gateway
  • All frontend API calls now routed through gateway

• Overhauled authentication and user session management

  • AuthService now uses backend tokens and profile endpoints
  • Improved login, registration, logout, and profile update logic
  • Robust error handling and token/session storage

• Refactored backend authentication and user ID propagation

  • API Gateway now validates JWTs directly (no auth service roundtrip)
  • Backend services extract user ID from gateway-injected header
  • Removed obsolete token validation endpoints and logic

• Enhanced project, document, task, notification, and external tools flows

  • Added document tab to project detail, improved document detail UI
  • Improved task editing with dropdowns and date pickers
  • Added notification bulk actions and deletion
  • External tools: OAuth provider listing, connect flow, and UI improvements

• Added comprehensive API documentation

  • Generated backend/docs/API_DOCUMENTATION.md covering all endpoints

---

Changes walkthrough 📝

	Relevant files
Enhancement	36 files auth_service.py Refactor auth logic to use Supabase session tokens and robust profile parsing +88/-130 auth_middleware.py JWT validation moved to gateway; direct JWT decode, no service call +38/-46  main.py Refactor request forwarding; filter headers, enforce body size, inject user ID +31/-10  main.py Use X-User-ID header for user authentication; fix assign_task param +7/-25    main.py Remove obsolete token validation/refresh endpoints              +2/-28    main.py Use X-User-ID header for user authentication                          +6/-23    main.py Use X-User-ID header for user authentication                          +6/-25    main.py Use X-User-ID header for user authentication                          +6/-25    external_tools.py Add type hints and TYPE_CHECKING for relationships              +11/-3    circuit_breaker.py Increase default request timeout to 10s                                    +2/-2      service_registry.py Register missing external_tools_service routes                      +3/-0      __init__.py Export all models in __all__ for easier imports                    +19/-0    project.py Add TYPE_CHECKING for relationships                                            +6/-0      document.py Add TYPE_CHECKING for relationships                                            +5/-1      notification.py Add TYPE_CHECKING for relationships                                            +4/-0      auth_service.dart Overhaul AuthService for API Gateway integration and robust session management +165/-130 document_detail_screen.dart Refactor document detail UI, add robust error/loading handling +126/-69 task_edit_screen.dart Refactor task edit form with dropdowns, date picker, and validation +126/-22 project_detail_screen.dart Add documents tab, fetch project documents, improve delete flow +126/-19 profile_screen.dart Use AuthService for profile data, add logout, improve UI  +118/-78 tool_calendar_screen.dart Add event model, date pickers, improved event creation and display +74/-16  project_edit_screen.dart Fetch and prefill project data for editing, robust error handling +91/-34  externaltools_screen.dart Add OAuth provider listing, connect flow, improved UI        +117/-19 document_models.dart Add DocumentType enum, helpers, and robust parsing              +59/-17  notifications_screen.dart Add notification deletion, bulk mark as read, improved UI +61/-3    register_screen.dart Integrate registration with backend, robust error/loading handling +54/-9    login_screen.dart Integrate login with backend, robust error/loading handling +30/-9    user_edit_screen.dart Prefill user edit form from AuthService, robust error handling +21/-4    external_tools_service.dart Add OAuth authorization and callback handling methods        +52/-0    app_router.dart Update document detail route to include projectId                +5/-13    task_detail_screen.dart Use getTaskDetails API for accurate task fetching                +4/-3      project_create_screen.dart Navigate to new project detail after creation                        +3/-2      notification_service.dart Add markAllNotificationsAsRead API call                                    +13/-0    account_settings_screen.dart Use AuthService for logout, ensure async and navigation    +7/-2      project_service.dart Add getTaskDetails API method                                                        +13/-0    documents_screen.dart Update document detail navigation to include projectId      +1/-1
Documentation	1 files API_DOCUMENTATION.md Add comprehensive API documentation for all services          +3956/-0
Bug fix	1 files home_screen.dart Fix notifications and external tools tab widgets                  +2/-2
Configuration changes	1 files docker-compose.yml Use DATABASE_URL env var for all backend services                +6/-6
Dependencies	1 files pubspec.yaml Update go_router and flutter_lints dependencies                    +2/-2
Additional files	2 files docker-compose.yml +0/-228  tests.py [link]

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 No relevant tests

🔒 Security concerns Sensitive information exposure: The frontend auth service logs request bodies and tokens in debug mode, which could expose sensitive authentication data in logs. Additionally, the JWT secret validation in the API gateway could fail silently if environment variables are not properly configured, potentially allowing unauthorized access.

⚡ Recommended focus areas for review Error Handling The datetime parsing logic in get_user_profile method has complex error handling with print statements and generic HTTPException responses. This could mask specific errors and make debugging difficult. The parsing logic should be simplified and error handling should be more specific. # Helper to handle datetime conversion robustly def _to_datetime(timestamp_val): if timestamp_val is None: return None if isinstance(timestamp_val, datetime): return timestamp_val # Already a datetime object if isinstance(timestamp_val, str): # Handle 'Z' for UTC if present, common in ISO strings # Also handle potential existing timezone info from fromisoformat compat try: if timestamp_val.endswith('Z'): # Replace Z with +00:00 for full ISO compatibility across Python versions return datetime.fromisoformat(timestamp_val[:-1] + '+00:00') dt_obj = datetime.fromisoformat(timestamp_val) # If it's naive, assume UTC, as Supabase timestamps are UTC if dt_obj.tzinfo is None: return dt_obj.replace(tzinfo=timezone.utc) return dt_obj except ValueError as ve: print(f"[WARN AuthService.get_user_profile] Could not parse timestamp string '{timestamp_val}': {ve}") return None # Or raise a specific error / handle as appropriate if isinstance(timestamp_val, (int, float)): # Supabase might return epoch timestamp try: return datetime.fromtimestamp(timestamp_val, tz=timezone.utc) except ValueError as ve: print(f"[WARN AuthService.get_user_profile] Could not parse numeric timestamp '{timestamp_val}': {ve}") return None print(f"[WARN AuthService.get_user_profile] Unexpected type for timestamp '{timestamp_val}': {type(timestamp_val)}") return None # Or raise error created_at_dt = _to_datetime(user.created_at) updated_at_dt = _to_datetime(user.updated_at) if user.updated_at else None if not isinstance(created_at_dt, datetime) and user.created_at is not None: # This implies parsing failed for a non-None original value or type was unexpected print(f"[ERROR AuthService.get_user_profile] Failed to convert user.created_at (value: {user.created_at}, type: {type(user.created_at)}) to datetime.") raise HTTPException(status_code=500, detail="Error processing user profile data (created_at).") return UserProfileDTO( id=user.id, email=user.email, full_name=user_metadata.get("full_name", ""), company_name=user_metadata.get("company_name", ""), role="user", # Default role created_at=created_at_dt, updated_at=updated_at_dt, ) except InvalidTokenException as e: # Re-raise specific known auth exceptions # This might be raised by supabase_manager.get_user() if token is truly invalid by Supabase raise e except HTTPException as e: # If we raised one above raise e except Exception as e: # Log the original error for server-side debugging print(f"[ERROR AuthService.get_user_profile] Unexpected exception processing user profile: {type(e).__name__} - {str(e)}") import traceback print(traceback.format_exc()) # Raise a generic server error to the client raise HTTPException(status_code=500, detail="An internal error occurred while processing the user profile.") Security Configuration JWT validation relies on environment variables for secret and audience, but there's no validation that these are properly configured at startup. Missing configuration could lead to runtime failures or security vulnerabilities. async def _validate_token(token: str) -> str: if not SUPABASE_JWT_SECRET: print('ERROR: SUPABASE_JWT_SECRET is not configured in the environment.') raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail='Authentication system configuration error.', ) try: payload = jwt.decode( token, SUPABASE_JWT_SECRET, algorithms=['HS256'], audience=SUPABASE_AUDIENCE # If validating issuer, add: issuer=SUPABASE_ISSUER ) user_id = payload.get('sub') if not user_id: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail='Invalid token: User ID (sub) not found in token.', ) return user_id except ExpiredSignatureError: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail='Token has expired.' ) except JWTError as e: print(f'JWTError during token validation: {str(e)}') # Server log raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail='Invalid token.', ) except Exception as e: print(f'Unexpected error during token validation: {str(e)}') # Server log raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail='An unexpected error occurred during token validation.', ) State Management The authentication service has complex state management with multiple async operations that could lead to race conditions. The initialize method and login/register flows modify _currentUser without proper synchronization, potentially causing inconsistent UI states. Future<void> initialize() async { try { final token = await _secureStorage.read(key: 'access_token'); if (token != null && token.isNotEmpty) { // Validate token by fetching profile final userProfile = await getProfile(); // getProfile uses the stored token _currentUser = userProfile; } else { _currentUser = null; } } catch (e) { // If getProfile fails (e.g. token expired), clear token and user await _secureStorage.delete(key: 'access_token'); await _secureStorage.delete(key: 'refresh_token'); _currentUser = null; } notifyListeners(); } // Login with email and password Future<UserProfileDTO> login(String email, String password) async { print('[AuthService.login] Attempting to login...'); print('[AuthService.login] URL: $baseUrl/auth/login'); print('[AuthService.login] Headers: {Content-Type: application/x-www-form-urlencoded}'); print('[AuthService.login] Body: {username: $email, password: <hidden>}'); final response = await http.post( Uri.parse('$baseUrl/auth/login'), headers: {'Content-Type': 'application/x-www-form-urlencoded'}, // Backend expects form data for login body: {'username': email, 'password': password}, // FastAPI's OAuth2PasswordRequestForm takes 'username' ); if (response.statusCode == 200) { print('[AuthService.login] Login API call successful. Status: ${response.statusCode}'); print('[AuthService.login] Response body: ${response.body}'); final data = jsonDecode(response.body); final tokenDto = TokenDTO.fromJson(data); await _secureStorage.write(key: 'access_token', value: tokenDto.accessToken); await _secureStorage.write(key: 'refresh_token', value: tokenDto.refreshToken); try { _currentUser = await getProfile(); notifyListeners(); return _currentUser!; // Assuming getProfile will throw if it can't return a user } catch (e) { print('[AuthService.login] Error fetching profile after login: ${e.toString()}'); // If getProfile fails after login, something is wrong. Clean up. await _secureStorage.delete(key: 'access_token'); await _secureStorage.delete(key: 'refresh_token'); _currentUser = null; notifyListeners(); throw Exception('Login succeeded but failed to fetch profile: ${e.toString()}'); } } else { print('[AuthService.login] Login API call failed. Status: ${response.statusCode}'); print('[AuthService.login] Response body: ${response.body}'); _currentUser = null; notifyListeners(); throw Exception('Login failed with status ${response.statusCode}: ${response.body}'); } } // Register with email, password, full name, and company name Future<UserProfileDTO> register(String email, String password, String fullName, String? companyName) async { print('[AuthService.register] Attempting to register...'); print('[AuthService.register] URL: $baseUrl/auth/register'); final requestBodyMap = { 'email': email, 'password': password, 'full_name': fullName, if (companyName != null && companyName.isNotEmpty) 'company_name': companyName, }; print('[AuthService.register] Headers: {Content-Type: application/json}'); // Mask password for logging final loggableBody = Map.from(requestBodyMap); loggableBody['password'] = '<hidden>'; print('[AuthService.register] Request body (raw): $loggableBody'); final response = await http.post( Uri.parse('$baseUrl/auth/register'), headers: {'Content-Type': 'application/json'}, body: jsonEncode(requestBodyMap), // Send original map with actual password ); if (response.statusCode == 200 || response.statusCode == 201) { // Typically 201 for register print('[AuthService.register] Register API call successful. Status: ${response.statusCode}'); print('[AuthService.register] Response body: ${response.body}'); final data = jsonDecode(response.body); final tokenDto = TokenDTO.fromJson(data); await _secureStorage.write(key: 'access_token', value: tokenDto.accessToken); await _secureStorage.write(key: 'refresh_token', value: tokenDto.refreshToken); try { _currentUser = await getProfile(); notifyListeners(); return _currentUser!; } catch (e) { print('[AuthService.register] Error fetching profile after registration: ${e.toString()}'); await _secureStorage.delete(key: 'access_token'); await _secureStorage.delete(key: 'refresh_token'); _currentUser = null; notifyListeners(); throw Exception('Registration succeeded but failed to fetch profile: ${e.toString()}'); } } else { print('[AuthService.register] Register API call failed. Status: ${response.statusCode}'); print('[AuthService.register] Response body: ${response.body}'); _currentUser = null; notifyListeners(); throw Exception('Register failed with status ${response.statusCode}: ${response.body}'); } }

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Use appropriate exception type The error message is misleading since InvalidCredentialsException typically indicates wrong username/password. Use a more appropriate exception type or create a custom exception for registration-specific issues like pending email confirmation. backend/api/auth_service/app/services/auth_service.py [50-53] if not response.session: # This case might happen if email confirmation is pending # Depending on desired UX, could raise an error or return a specific DTO - raise InvalidCredentialsException("User registration succeeded, but session not available. Please confirm your email.") + raise HTTPException(status_code=400, detail="User registration succeeded, but session not available. Please confirm your email.") Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that using InvalidCredentialsException is semantically misleading for a scenario where user registration succeeded but requires email confirmation. The proposed change to use HTTPException with a 400 status code provides a more accurate error signal to the client, improving the API's correctness and usability.	Medium
	Prevent trailing widget overflow The Row widget in trailing can overflow on smaller screens when both buttons are present. Consider using a PopupMenuButton or limiting the number of visible actions to prevent layout issues. frontend/lib/features/home/screens/notifications_screen.dart [184-199] -trailing: Row( - mainAxisSize: MainAxisSize.min, - children: [ +trailing: PopupMenuButton<String>( + onSelected: (value) { + if (value == 'read' && !notif.isRead) { + _markAsRead(notif.id); + } else if (value == 'delete') { + _deleteNotification(notif.id); + } + }, + itemBuilder: (context) => [ if (!notif.isRead) - IconButton( - icon: const Icon(Icons.mark_email_read, color: AppColors.primary), - tooltip: 'Marcar como leído', - onPressed: () => _markAsRead(notif.id), + const PopupMenuItem( + value: 'read', + child: Row(children: [Icon(Icons.mark_email_read), SizedBox(width: 8), Text('Marcar como leído')]), ), - IconButton( - icon: Icon(Icons.delete_outline, color: Colors.grey[600]), - tooltip: 'Eliminar notificación', - onPressed: () => _deleteNotification(notif.id), + const PopupMenuItem( + value: 'delete', + child: Row(children: [Icon(Icons.delete_outline), SizedBox(width: 8), Text('Eliminar')]), ), ], ), Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential UI overflow issue in the ListTile's trailing widget. Using a Row with multiple IconButtons is not robust. The proposed solution of using a PopupMenuButton is an excellent UI pattern to prevent layout errors and improve user experience on various screen sizes.	Medium
	Use enum name property The enum-to-string conversion using toString().split('.').last is fragile and will break if the enum structure changes. Use a proper enum extension or mapping function instead for more robust code. frontend/lib/features/home/screens/externaltools_screen.dart [233] -leading: Icon(_iconForProvider(provider.type.toString().split('.').last.toLowerCase())), // Get string value of enum +leading: Icon(_iconForProvider(provider.type.name.toLowerCase())), // Use .name property for enum Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that using toString().split('.').last to get an enum's string value is fragile. The proposed change to use the .name property is the modern, recommended practice in Dart, leading to more robust and readable code.	Low
	Fix misplaced docstring The docstring is placed after the early return statement, making it unreachable and potentially confusing. Move the docstring to the beginning of the function. backend/api/api_gateway/middleware/auth_middleware.py [18-24] async def auth_middleware( request: Request, call_next: Callable[[Request], Awaitable[JSONResponse]] ) -> JSONResponse: + """ + Middleware for authentication. + """ if request.method == "OPTIONS": return await call_next(request) - """ - Middleware for authentication. [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 3 __ Why: The suggestion is correct. The docstring is placed after an early return statement, which means it's just an unassigned string literal and not a proper docstring. Moving it to the beginning of the function is the correct fix, ensuring that documentation generation tools and IDEs can correctly identify it. This improves code quality and maintainability.	Low
More