Error Handling & Logging

Relevant source files

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

• components/error-boundary.tsx
• settings/_components/diagnostics.tsx
• api/enhance-resume/[id]/route.ts
• api/resumes/upload/route.ts
• enhance/[id]/_components/enhance-interface.tsx
• layout.tsx
• README.md
• INTEGRATION_GUIDE.md

The GUC Resume Enhancer project employs a multi-layered approach to error handling and logging, ensuring both a smooth user experience and robust backend diagnostics. Client-side errors are managed through a global error boundary and user-facing notifications (toasts and alerts), while server-side issues are captured in try...catch blocks within API routes, logged to a persistent database, and made accessible through a dedicated diagnostics interface.

This system is designed to gracefully handle unexpected application states, provide clear feedback to users, and give administrators the tools to monitor and troubleshoot system activity. The core components include the ErrorBoundary for fatal UI crashes, the sonner library for transient notifications, and a custom logger utility that writes to the SystemLog database table.

1. Client-Side Error Handling

Client-side error handling focuses on preventing application crashes and providing immediate, contextual feedback to the user.

1.1. Global Error Boundary

A global ErrorBoundary React component wraps the entire application to catch JavaScript errors anywhere in the component tree, preventing a white screen of death and displaying a user-friendly fallback UI.

• Implementation: The ErrorBoundary is a class component that uses getDerivedStateFromError to capture errors during rendering and componentDidCatch to log error information to the console in development environments.
• Location: It is implemented in the root layout, wrapping all page content.
• Fallback UI: If an error is caught, it displays a destructive Alert with a message "Something went wrong" and a button to navigate back to the home page, which also resets the error state.

Sources: components/error-boundary.tsx, layout.tsx:19-27

The following diagram illustrates the logic of the ErrorBoundary component.

1.2. User Notifications (Toasts & Alerts)

For non-fatal errors, such as failed API requests or validation issues, the application uses toasts and alerts to inform the user without interrupting their workflow.

• Toasts: The sonner library is used to display transient, non-blocking notifications. Functions like toast.error() and toast.success() are called within component logic to provide feedback on asynchronous operations. For example, when a resume enhancement fails, a toast appears with the message "Enhancement failed. Please try again."
• Alerts: The Alert component from shadcn/ui is used for more persistent, in-context messages. For instance, if a user tries to enhance a resume without configuring API keys, a prominent alert is displayed on the enhancement page.

Sources: enhance/[id]/_components/enhance-interface.tsx:243-246, 311-319, settings/_components/diagnostics.tsx:75-77

1.3. Component-Level State Management

Components manage their own error states for specific UI sections. For example, the EnhanceInterface component uses a loadError state to handle failures when fetching the original resume file for preview. If an error occurs, a specific error message is displayed within the preview pane instead of the document.

Sources: enhance/[id]/_components/enhance-interface.tsx:142, 192-200, 471-479

2. Server-Side Error Handling & Logging

The backend API routes are designed to handle errors robustly, log them for diagnostics, and return meaningful responses to the client.

2.1. API Route Error Handling

All primary API routes, such as for file uploads and resume enhancements, wrap their logic in try...catch blocks.

• Error Catching: When an exception occurs (e.g., database error, failed call to an external AI provider), the catch block takes over.
• Logging: The error is logged using the central logger utility.
• Response: A JSON object with an error message and an appropriate HTTP status code (e.g., 400, 500) is returned to the client.

This pattern ensures that server-side failures are always caught, logged, and communicated clearly to the frontend.

Sources: api/enhance-resume/[id]/route.ts:252-260, api/resumes/upload/route.ts:133-144

The sequence diagram below shows the flow for a failed resume enhancement request.

2.2. Centralized Logger

A logger utility is used for standardized logging across the backend. While the source file lib/logger.ts is not provided, its usage in API routes reveals its functionality. It appears to be a wrapper around the Prisma client that creates entries in the SystemLog table.

The logger supports different log levels, such as info and error.

• logger.info(category, message, metadata, userId)
• logger.error(category, message, metadata, userId)

Sources: api/enhance-resume/[id]/route.ts:226-231, 244-249, api/resumes/upload/route.ts:123-129, INTEGRATION_GUIDE.md

2.3. SystemLog Database Model

Error and activity logs are persisted in the SystemLog table in the database, as mentioned in the project's README.md. The Diagnostics component reveals the structure of the log entries.

Field	Type	Description
id	String	Unique identifier for the log entry.
level	String	The severity level of the log (e.g., 'error', 'warning', 'info', 'debug').
category	String	The functional area of the log (e.g., 'resume_enhancement', 'auth').
message	String	A human-readable description of the event.
metadata	JSON	A JSON object containing additional contextual data.
createdAt	String	The timestamp when the log was created.

Sources: README.md, settings/_components/diagnostics.tsx:21-28, 161-164

3. Diagnostics & Monitoring

The application provides a user interface for administrators to view and manage system logs.

3.1. Diagnostics UI

The Diagnostics component, located in the settings section, provides a comprehensive view of the SystemLog table.

• Log Viewing: Displays a list of logs with their level, category, message, and timestamp.
• Filtering: Allows filtering logs by level and category.
• Log Details: Individual logs can be expanded to view the raw metadata JSON.
• Log Management: Provides functionality to refresh the log list, export all logs to a JSON file, and clear all logs from the database.

Sources: settings/_components/diagnostics.tsx

The following diagram shows the relationship between the components of the logging and diagnostics system.

3.2. Log Levels and Categories

The diagnostics UI defines a set of log levels and categories for filtering.

Log Levels	Log Categories
error	api_key
warning	resume_enhancement
info	auth
debug	system
all	database
	file_upload
	all

Sources: settings/_components/diagnostics.tsx:21-28, 30-45

Summary

The error handling and logging system in GUC Resume Enhancer is a well-rounded solution that addresses both user experience and backend maintainability. On the client side, it uses an ErrorBoundary to prevent crashes and provides clear, non-intrusive feedback through toasts and alerts. On the server side, it systematically catches exceptions in API routes, logs detailed information to a persistent SystemLog table via a centralized logger, and exposes these logs through a powerful diagnostics interface. This comprehensive strategy ensures application stability, aids in rapid troubleshooting, and provides valuable insights into system activity.