Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• app/(tabs)/analyze.tsx
• app/oauth/callback.tsx
• hooks/use-auth.ts
• lib/_core/api.ts
• scripts/reset-project.js
• server/_core/llm.ts
• server/_core/oauth.ts
• server/_core/trpc.ts
• todo.md

Introduction

Troubleshooting in the aidoit4u-mobile-app project involves a combination of frontend state management, robust API communication, backend error handling, and extensive logging. The system is designed to provide clear feedback during critical processes like authentication and API interactions. UI components manage their own loading and error states, while a centralized API client handles network errors and backend responses. The backend uses specific error codes for authentication and authorization, ensuring predictable client-side error handling.

The project's todo.md outlines a comprehensive plan for future enhancements in error handling, including the implementation of error boundaries, retry logic for failed API calls, and handling for network connectivity issues. This document details the current troubleshooting mechanisms and debugging strategies based on the existing codebase.

Sources: todo.md:59-64, lib/_core/api.ts, app/oauth/callback.tsx

Frontend Error Handling

The frontend employs several patterns for managing and diagnosing issues, from component-level state to a centralized API call handler.

Component-Level State Management

Individual screens manage their own states, such as loading, success, and error, to provide immediate user feedback.

OAuth Callback Screen

The OAuthCallback component is a critical entry point for user authentication and features a robust state machine to handle the complex flow of exchanging an authorization code for a session token. It uses a status state (processing, success, error) and an errorMessage state to display clear information to the user. Extensive logging throughout the useEffect hook helps developers trace the authentication flow.

Sources: app/oauth/callback.tsx:11-13, 15-20

The following diagram illustrates the logic within the OAuthCallback component.

Document Analysis Screen

The AnalyzeScreen uses the isAnalyzing state to disable the "Analyze" button and show a loading message during a mock API call. If the analysis is successful, the UI transitions to display the results. This prevents duplicate submissions and informs the user that a process is underway. The "Analyze" button is also disabled if no file is selected and no text is pasted, preventing invalid requests.

Sources: app/(tabs)/analyze.tsx:25-26, 61, 153-157

Centralized API Client (apiCall)

All network requests are funneled through the apiCall function in lib/_core/api.ts. This function provides a centralized location for handling authentication, headers, and, most importantly, error responses.

Key error handling features:

• It checks if the response is ok. If not, it attempts to parse a JSON error message from the response body.
• If parsing fails, it uses the raw response text as the error message.
• It throws a new Error with the detailed message, which can be caught by the calling function (e.g., in a React Query mutation or a try/catch block).
• Extensive console.log and console.error calls are used to trace the request lifecycle, status, headers, and any errors.

Sources: lib/_core/api.ts:47-66

The sequence diagram below shows the flow of a request through apiCall, including the error path.

Authentication Hook (useAuth)

The useAuth hook is responsible for fetching and managing the current user's authentication state. It includes loading and error states to track the process.

• fetchUser Logic: This function wraps the user-fetching logic in a try...catch block. On failure, it populates the error state.
• Platform-Specific Logic: It distinguishes between web (cookie-based auth via Api.getMe()) and native (token-based auth via Auth.getSessionToken()).
• Logging: The hook contains numerous console.log and console.error statements to aid in debugging authentication issues, showing the platform, token status, and user data.

Sources: hooks/use-auth.ts:15-62

The following diagram shows the data flow for fetching a user with the useAuth hook.

Backend Error Handling

The server-side application has structured error handling for API endpoints, particularly for authentication and external service calls.

tRPC Procedures

The tRPC setup in server/_core/trpc.ts defines middleware to protect routes.

• protectedProcedure: Checks if ctx.user exists. If not, it throws a TRPCError with code UNAUTHORIZED.
• adminProcedure: Checks if the user is an admin. If not, it throws a TRPCError with code FORBIDDEN.

These specific error codes allow the client to implement targeted error handling, such as redirecting to a login page or showing a permissions-denied message.

Procedure	Condition	Error Code
protectedProcedure	!ctx.user	UNAUTHORIZED
adminProcedure	!ctx.user or ctx.user.role !== 'admin'	FORBIDDEN

Sources: server/_core/trpc.ts:13-39

OAuth Endpoints

The Express routes for OAuth callbacks in server/_core/oauth.ts contain try...catch blocks to handle failures during the code-for-token exchange or user info fetching. If an error occurs, the server responds with a 500 status code and a JSON error message. It also logs the error to the console for server-side debugging.

Sources: server/_core/oauth.ts:70-73, 87-90

LLM Service (invokeLLM)

The invokeLLM function, which communicates with an external AI service, has two primary error checks:

1. API Key Check: It calls assertApiKey() to ensure ENV.forgeApiKey is configured, throwing an error if it's missing.
2. Fetch Request: It checks if the fetch response is ok. If not, it throws an error containing the HTTP status, status text, and response body, providing detailed context for the failure.

Sources: server/_core/llm.ts:192-195, 227-230

Logging and Development Tools

Console Logging

The application uses console.log, console.warn, and console.error extensively across both the frontend and backend to provide a detailed trace of execution. This is particularly evident in authentication-related files like app/oauth/callback.tsx, hooks/use-auth.ts, and lib/_core/api.ts, where every major step, state change, and error is logged.

Sources: app/oauth/callback.tsx, hooks/use-auth.ts, lib/_core/api.ts

Project Reset Script

For development and troubleshooting of the local environment, the scripts/reset-project.js script provides a way to reset the project to a clean state. It includes a try...catch block to report any errors that occur during the file system operations, preventing a partially-completed reset from going unnoticed.

Sources: scripts/reset-project.js:90-92

Planned Troubleshooting Enhancements

The todo.md file outlines several key features planned for improving error handling and validation, which are crucial for a production-ready application.

Feature	Description	Status
Form Validation	Add validation to all input screens.	Not Started
Error Boundaries	Implement React Error Boundaries to catch rendering errors.	Not Started
Error Message UI	Create dedicated UI components for displaying errors.	Not Started
Retry Logic	Add retry logic for failed API calls.	Not Started
Network Connectivity	Handle network connectivity issues gracefully.	Not Started

Sources: todo.md:59-64