Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The GUC Resume Enhancer is a full-stack web application built on Next.js, designed to help job seekers optimize their resumes using various AI providers. The platform supports user authentication, resume file management, AI-powered text enhancement, and PDF downloads. Its architecture is modular, separating concerns between the frontend user experience, backend API logic, data persistence, and external service integrations.
The system is designed to operate in two modes: a "Full Mode" with user accounts, history, and API key management, and a "Light Mode" for quick, anonymous enhancements. This dual-mode support is a core architectural consideration, providing flexibility for different user needs. The backend is centered around Next.js API routes which handle business logic, database interactions via Prisma, and communication with AI services.
Sources: README.md:3-5, 20-23
Tech Stack
The application utilizes a modern tech stack based on TypeScript for both frontend and backend development.
Sources: README.md:27-55, package.json
Frontend
| Category | Technology | Description |
|---|---|---|
| Framework | Next.js 14.2 (App Router) | The primary framework for server-side rendering and client-side navigation. |
| Language | TypeScript 5.2 | Provides static typing for improved code quality and maintainability. |
| Styling | Tailwind CSS 3.3 | A utility-first CSS framework for rapid UI development. |
| UI Components | Radix UI, shadcn/ui | A set of primitives for building accessible and customizable UI components. |
| State Mgmt | Zustand + Jotai | For managing global and local application state. |
| Data Fetching | TanStack Query (React Query) + SWR | Handles server-state management, caching, and data synchronization. |
| Forms | React Hook Form + Zod | For building and validating forms. |
| PDF Handling | react-pdf, pdfjs-dist | Used for rendering PDF documents directly in the browser for preview. |
Sources: README.md:29-41, package.json:34-124
Backend
| Category | Technology | Description |
|---|---|---|
| Runtime | Node.js (via Next.js) | The JavaScript runtime environment. |
| Database | PostgreSQL | The relational database for storing user data, resumes, and enhancements. |
| ORM | Prisma 6.7 | A next-generation ORM for TypeScript that handles database access and migrations. |
| Authentication | NextAuth 4.24 | Manages user sessions, sign-up, and sign-in. |
| File Storage | Supabase Storage (or AWS S3) | Used for storing uploaded resume files (PDF, DOCX). |
| File Processing | pdf-parse, mammoth | Libraries to extract raw text content from PDF and DOCX files on the server. |
| PDF Generation | jspdf | Used to generate downloadable PDF files from the enhanced resume text. |
| AI Providers | OpenAI, Anthropic, Google Gemini | External LLM services used for the core resume enhancement functionality. |
Sources: README.md:43-55, INTEGRATION_GUIDE.md:12-22, api/resumes/upload/route.ts:7-8
System Architecture
The application follows a monolithic architecture with a clear separation between the frontend and backend logic, all contained within a single Next.js project. The client-side is built with React components, while the backend consists of API routes that interface with the database, file storage, and external AI services.
This diagram shows the high-level interaction between the main components of the system.
Core Components
Database Schema
The application uses a PostgreSQL database managed by the Prisma ORM. The schema is defined in schema.prisma and consists of several key models to manage users, resumes, and AI enhancements.
The following ER diagram illustrates the relationships between the main database models.
Sources: README.md:111-117, INTEGRATION_GUIDE.md:65-69
File Storage
The application uses Supabase Storage to securely store uploaded resume files. A private bucket named resumes is used.
- Bucket Name:
resumes - Access: Private
- Structure: Files are organized by user ID to ensure data isolation:
resumes/{userId}/{timestamp}-{fileName}.
Storage policies are implemented using SQL to enforce security at the bucket level:
- Authenticated users can only upload files into their own
/{userId}/folder. - Users can only read and delete files from their own folder.
Sources: SUPABASE_SETUP.md:19-51, 140-146
AI Service Integration
The core enhancement feature is powered by integrations with multiple AI providers: OpenAI, Anthropic, and Google Gemini. The backend dynamically calls the appropriate service based on the user's active API key configuration.
- Provider Selection: Determined by the
providerfield in the user's activeUserApiKeyrecord. - API Calls: The
api/enhance-resume/[id]/route.tsendpoint contains dedicated helper functions (enhanceWithOpenAI,enhanceWithAnthropic,enhanceWithGemini) to handle the specific request formats for each AI service. - Prompts: Each enhancement type (
skills_certifications,project_experience,client_quality) has a corresponding prompt tailored to instruct the AI model on how to rewrite the resume content. The system prompt configures the AI to act as a professional resume writer.
Sources: api/enhance-resume/[id]/route.ts:10-128, README.md:57-68
Key Data Flows
Resume Upload Flow
This sequence diagram illustrates the process from when a user uploads a resume file to when it is stored and ready for enhancement.
Resume Enhancement Flow
This diagram shows the steps involved when a user requests an AI enhancement for an uploaded resume.
API Endpoints
The backend exposes several RESTful API endpoints for managing resumes, enhancements, and API keys.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/resumes/upload | Upload a new resume file. |
GET | /api/resumes/:id | Get details for a specific resume. |
DELETE | /api/resumes/:id | Delete a resume. |
POST | /api/enhance-resume/:id | Create a new AI enhancement for a resume. |
GET | /api/download-resume/:id | Download an enhanced resume as a PDF. |
GET | /api/api-keys | List the current user's API keys. |
POST | /api/api-keys | Add a new API key for an AI provider. |
DELETE | /api/api-keys/:id | Delete an API key. |
Sources: README.md:119-135, INTEGRATION_GUIDE.md:36-46, api/download-resume/[id]/route.ts
Configuration
The application is configured through environment variables defined in a .env file.
| Variable | Description | Example |
|---|---|---|
DATABASE_URL | Connection string for the PostgreSQL database. | postgresql://user:pass@host:port/db |
NEXTAUTH_SECRET | A secret key for signing NextAuth sessions. | your-random-secret-key |
NEXTAUTH_URL | The canonical URL of the application. | http://localhost:3000 |
NEXT_PUBLIC_SUPABASE_URL | The public URL for the Supabase project. | https://id.supabase.co |
NEXT_PUBLIC_SUPABASE_ANON_KEY | The anonymous public key for Supabase. | your-anon-key-here |
SUPABASE_SERVICE_ROLE_KEY | The secret service role key for backend Supabase operations. | your-service-role-key-here |
ENCRYPTION_KEY | A 32-character key for encrypting user API keys in the database. | your-32-character-encryption-key |
OPENAI_API_KEY | (Optional) System-wide key for OpenAI. | sk-... |
Sources: README.md:78-96, SUPABASE_SETUP.md:58-76