Frontend Architecture

Relevant source files

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

• layout.tsx
• package.json
• page.tsx
• enhance/[id]/_components/enhance-interface.tsx
• dashboard/_components/upload-section.tsx
• components.json
• README.md
• history/_components/history-list.tsx

The frontend of the GUC Resume Enhancer is a modern web application built with Next.js 14 and TypeScript. It provides a comprehensive user interface for resume management, including uploading, AI-powered enhancement, history tracking, and downloading. The architecture is based on the Next.js App Router, promoting a server-centric approach with React Server Components and client-side interactivity where needed.

The application is styled using Tailwind CSS and utilizes a component library built with shadcn/ui on top of Radix UI primitives. This ensures a consistent, accessible, and maintainable UI. State management is handled through a combination of local component state (useState, useEffect) for UI logic and libraries like Zustand and Jotai for more complex global state needs.

Sources: README.md:21-30, package.json, layout.tsx

Tech Stack and Dependencies

The frontend relies on a modern toolchain centered around the React ecosystem. Key dependencies are defined in package.json.

Library/Tool	Version	Description
next	14.2.28	The core React framework, using the App Router.
react	18.2.0	The UI library for building components.
typescript	5.2.2	Provides static typing for the codebase.
tailwindcss	3.3.3	A utility-first CSS framework for styling.
@radix-ui/*	various	A set of unstyled, accessible UI primitives.
lucide-react	0.446.0	A library of simply designed icons.
zustand / jotai	5.0.3 / 2.6.0	State management libraries.
react-hook-form	7.53.0	For building and managing forms.
sonner	1.5.0	A toast notification library for user feedback.
react-pdf	10.2.0	Used for rendering PDF documents in the browser.
marked	16.4.0	A markdown parser for rendering enhanced resume content.
dompurify	3.0.6	Sanitizes HTML to prevent XSS attacks.

Sources: package.json:4-13, 31-105, README.md:21-30, enhance/[id]/_components/enhance-interface.tsx:21, 22

Project Structure and Routing

The project follows the Next.js App Router convention, where directories define routes. This structure organizes the application by feature.

/
├── app/
│   ├── (main)/
│   │   ├── page.tsx                # Landing Page
│   │   ├── layout.tsx              # Root Layout
│   ├── admin/resumes/              # Admin-specific resume management page
│   ├── dashboard/                  # Main user dashboard for uploads
│   ├── enhance/[id]/               # Resume enhancement interface
│   ├── history/                    # User's enhancement history page
│   └── api/                        # API routes (backend)
├── components/
│   └── ui/                         # Reusable UI components from shadcn/ui
├── lib/                            # Utility functions
└── public/                         # Static assets (images, etc.)

Sources: README.md:120-132, layout.tsx, page.tsx, admin/resumes/page.tsx, dashboard/page.tsx, enhance/[id]/_components/enhance-interface.tsx, history/_components/history-list.tsx

Root Layout

The main entry point for the UI is app/layout.tsx. It defines the root HTML structure, includes global CSS, and wraps all pages in a set of providers.

The RootLayout component:

• Sets the HTML language to en.
• Applies the Inter font.
• Defines global metadata for SEO.
• Wraps children in an <ErrorBoundary>, a <Providers> component (likely for context, themes, or data fetching libraries), and a <Header>.

Sources: layout.tsx:1-41

UI Components

The application uses shadcn/ui for its component library, which is configured in components.json. This provides a set of reusable, composable, and themeable components built on Radix UI.

• Configuration: The components.json file defines path aliases (@/components, @/lib/utils) and Tailwind CSS settings.
• Base Components: Common UI elements like Button, Card, Input, Select, Progress, and Alert are used extensively to build the interface.
• Layout Components: The Sheet component is used for side panels, providing a consistent way to display content like mobile navigation or settings.

The diagram below shows how a page is composed using these components.

Core Features and Flows

1. Resume Upload

The resume upload functionality is encapsulated in the UploadSection component. It allows users to select or drag-and-drop a file, validates it, and sends it to the backend.

Key Logic:

1. File Selection: A user can select a file via a file input or drag-and-drop.
2. Validation: The handleFileSelect function performs client-side validation:
   • File Type: Checks if the file is a PDF (application/pdf) or Word document (.docx, .doc).
   • File Size: Ensures the file is no larger than 10MB.
3. State Management: The component uses useState to manage the selected file, isUploading status, uploadProgress, and any error messages.
4. API Call: The handleUpload function constructs a FormData object and sends a POST request to the /api/upload-resume endpoint (note: the code shows /api/upload-resume, but the integration guide and README mention /api/resumes/upload).
5. Redirection: Upon a successful upload, the user is redirected to the enhancement page for the newly created resume (/enhance/${data.resumeId}).

Sources: dashboard/_components/upload-section.tsx:10-101

This sequence diagram illustrates the upload flow from the user's perspective.

2. Resume Enhancement

The EnhanceInterface component is the heart of the application, providing the UI for AI-powered resume enhancement.

Component Logic:

1. Data Fetching: On load, the component receives the resume object and a hasApiKeys boolean as props. It then fetches the original resume file from a proxy endpoint (/api/proxy-pdf/[id]) to display it.

2. State Management: It uses useState to manage selectedEnhancement, isEnhancing status, progress, the currentEnhancement being viewed, and the previewMode.

3. Enhancement Selection: The user selects from a predefined list of enhancement types.

   Value	Label	Description
   skills_certifications	Skills & Certifications	Highlight trade skills, licenses, and certifications
   project_experience	Project Experience	Showcase completed work and technical expertise
   client_quality	Client Success & Quality	Emphasize customer satisfaction and quality work

4. API Call: The handleEnhance function sends a POST request to /api/enhance-resume/[id] with the selected enhancementType.

5. Streaming Response: The component is designed to handle a streaming response from the server. It reads the stream, parses data: events, and updates the progress bar.

6. Content Rendering:

   • The original resume (if PDF) is rendered using react-pdf.
   • The enhanced content, which is Markdown, is sanitized using DOMPurify and then converted to HTML using marked before being rendered. This prevents XSS vulnerabilities.

7. History: The component lists previous enhancements for the same resume, allowing the user to switch between them.

Sources: enhance/[id]/_components/enhance-interface.tsx:68-82, 114-123, 199-253, 470-496

The following diagram shows the enhancement process flow.

Conclusion

The frontend architecture of the GUC Resume Enhancer is robust, modern, and feature-rich. By leveraging Next.js 14, TypeScript, and a well-defined component system with shadcn/ui, it provides a scalable and maintainable foundation. The clear separation of concerns into pages and components, coupled with well-designed data flows for core features like file uploads and AI enhancement, results in a high-quality user experience. The use of server components and client-side interactivity is well-balanced, ensuring both performance and dynamic functionality.

Sources: README.md:21-30, package.json, layout.tsx