AI-Powered Resume Optimization Platform
Transform any resume into an ATS-optimized, single-page PDF with intelligent content enhancement powered by Groq AI (with Google Gemini as fallback).
KairosCV is a full-stack web application that helps job seekers optimize their resumes for Applicant Tracking Systems (ATS). Upload your resume in PDF, DOCX, or TXT format and receive an AI-enhanced, professionally formatted PDF — guaranteed to fit on exactly one page.
- Multi-Format Upload — PDF, DOCX, and TXT files supported
- AI-Powered Enhancement — Groq (primary) or Google Gemini (fallback) rewrites and strengthens your content
- Exact Single-Page Output — Puppeteer scale fitting ensures the PDF always fills one full page with no clipping
- Three Professional Templates — Professional (LaTeX-inspired), Modern (blue accents), Classic (traditional serif)
- Real-Time Progress — Server-Sent Events stream live processing updates
- User Accounts — Supabase Auth with email/password login and signup
- Resume Dashboard — View and re-download all previously generated resumes
- Profile & Avatars — Settings page with 30+ DiceBear avatar styles
- Fair Usage — 3 free generations per rolling 24-hour window
- Privacy-First — Files are processed server-side and cleaned up after download
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript |
| UI | React 19, Radix UI, Tailwind CSS |
| AI | Groq (primary) · Google Gemini (fallback) |
| PDF Generation | Puppeteer / puppeteer-core |
| Templates | Custom HTML + Handlebars |
| Auth & Storage | Supabase (Auth, Storage, Postgres) |
| Parsing | pdf-parse, mammoth, unpdf |
| Validation | Zod |
| Package Manager | pnpm |
- Node.js >= 18.17.0
- pnpm >= 8.0.0 — install
- Groq API Key — get one (or a Google Gemini key as fallback)
- Supabase project — create one (optional for local no-auth mode)
git clone https://github.com/8harath/KairosCV.git
cd KairosCVpnpm installCreate .env.local in the project root:
# ── AI ────────────────────────────────────────────
# Groq is the primary provider. Gemini is used as fallback if GROQ_API_KEY is absent.
GROQ_API_KEY=your-groq-api-key
GOOGLE_GEMINI_API_KEY=your-gemini-api-key # optional fallback
GEMINI_MODEL=gemini-1.5-flash
GEMINI_TEMPERATURE=0.3
GEMINI_MAX_TOKENS=2048
# ── App ───────────────────────────────────────────
NODE_ENV=development
MAX_FILE_SIZE=5242880
UPLOAD_DIR=uploads
# ── Auth / Trial limits ───────────────────────────
# Set DISABLE_AUTH=true to skip login for local development
DISABLE_AUTH=true
NEXT_PUBLIC_DISABLE_AUTH=true
ENABLE_TRIAL_LIMIT=false
TRIAL_LIMIT=3
TRIAL_WINDOW_HOURS=24
# ── Supabase (required in production) ────────────
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
SUPABASE_INPUT_BUCKET=resume-inputs
SUPABASE_OUTPUT_BUCKET=resume-outputs
SUPABASE_JSON_BUCKET=resume-json
USE_SUPABASE_STORAGE=false
USE_SUPABASE_TRIALS=false
# ── Puppeteer ─────────────────────────────────────
# Leave empty locally — the app auto-detects your Chrome installation.
PUPPETEER_EXECUTABLE_PATH=
# Required on Vercel — URL to a hosted Sparticuz Chromium pack.
CHROMIUM_BINARY_URL=pnpm devOpen http://localhost:3000.
- Upload — drag and drop your resume (PDF, DOCX, or TXT, up to 5 MB)
- Watch — real-time progress bar tracks parsing → AI enhancement → PDF generation
- Download — get a professionally formatted, ATS-ready PDF
| Format | Extension | Max Size |
|---|---|---|
.pdf |
5 MB | |
| Word | .docx |
5 MB |
| Plain text | .txt |
5 MB |
| ID | Name | Style |
|---|---|---|
professional |
Professional | LaTeX/CMU Serif — clean academic layout |
modern |
Modern | Inter sans-serif with blue accents |
classic |
Classic | Georgia serif with horizontal rules |
- Contact information formatted for ATS parsing
- Work experience bullets rewritten with action verbs and metrics
- Skills organized into categories (Languages, Frameworks, Tools, Databases)
- Education structured correctly for ATS
- Optional summary, certifications, awards, publications, volunteer work, and custom sections
KairosCV/
├── app/
│ ├── api/
│ │ ├── upload/route.ts # File upload
│ │ ├── stream/[fileId]/route.ts # SSE progress
│ │ ├── download/[fileId]/route.ts
│ │ ├── json/[fileId]/route.ts # Parsed resume JSON
│ │ ├── resume/[id]/route.ts # Saved resume management
│ │ ├── profile/route.ts # User profile API
│ │ └── health/route.ts
│ ├── auth/ # Login / signup / callback
│ ├── dashboard/ # Resume history
│ ├── optimize/ # Main upload & processing UI
│ ├── settings/ # Profile & avatar settings
│ ├── contact/ # Contact form (EmailJS)
│ └── layout.tsx / page.tsx
├── lib/
│ ├── ai/ # Gemini service, field classification
│ ├── parsers/ # PDF, DOCX, TXT enhanced parsers
│ ├── pdf/
│ │ └── pdf-generator.ts # Puppeteer PDF generation + scale fitting
│ ├── templates/
│ │ ├── jakes-resume-improved.html # Professional template
│ │ ├── modern.html
│ │ ├── classic.html
│ │ └── template-renderer.ts
│ ├── schemas/resume-schema.ts # Zod resume schema
│ ├── storage/ # Supabase + local file storage
│ ├── supabase/ # Supabase client helpers
│ ├── trials/ # Usage limiting logic
│ └── resume-processor.ts # Main processing pipeline
├── components/ # React UI components
│ ├── file-uploader.tsx
│ ├── progress-tracker.tsx
│ ├── results-panel.tsx
│ ├── header.tsx / navigation.tsx
│ └── ...
└── __tests__/ # Vitest unit tests
pnpm dev # Development server (http://localhost:3000)
pnpm build # Production build
pnpm start # Start production server
pnpm lint # ESLint
pnpm test # Vitest (watch mode)
pnpm test:run # Vitest (CI / single run)
pnpm test:ui # Vitest with browser UI
npx tsc --noEmit # Type checking- Create a Web Service and connect your GitHub repo
- Build command:
pnpm install && pnpm build - Start command:
pnpm start - Add environment variables in the Render dashboard (see
.env.localabove) - Set
PUPPETEER_EXECUTABLE_PATH=/opt/render/.cache/puppeteer/chrome
See docs/RENDER_DEPLOYMENT.md for full instructions.
- Set Node.js runtime to 20 or 22
- Set
CHROMIUM_BINARY_URLto a hosted Sparticuz Chromium pack URL - Leave
PUPPETEER_EXECUTABLE_PATHempty — the app detects the Vercel environment automatically - Deploy the
mainbranch
See docs/DEPLOYMENT.md for full instructions.
Upload (PDF / DOCX / TXT)
│
▼
File Validation ──────────────────────────────┐
│ │
▼ SSE events
Parse → Extract Sections streamed to
│ the browser
▼
Gemini AI Enhancement
│
▼
HTML Template Rendering (Professional / Modern / Classic)
│
▼
Puppeteer PDF Generation
├── Viewport set to 720 px (print content width)
├── Measure scrollHeight
├── Compute scale = 960 px / scrollHeight
└── Generate PDF — always exactly one page
│
▼
Download link returned
- File type validated with magic-number checks (not just extension)
- All uploaded content is sanitized before HTML rendering (XSS prevention)
- 5 MB upload limit enforced on both client and server
- Temporary files cleaned up after download or expiry
- API keys stored in environment variables — never in source code
- Supabase Row Level Security for per-user data isolation
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Commit using Conventional Commits:
feat(pdf): add landscape template option fix(parser): handle empty education section - Push and open a Pull Request against
main
Scopes: parser, ai, pdf, ui, api, auth, deploy
Additional guides are in the docs/ directory:
| File | Description |
|---|---|
| DEPLOYMENT.md | Vercel deployment guide |
| RENDER_DEPLOYMENT.md | Render.com deployment guide |
| SUPABASE_SETUP.md | Supabase project setup |
| EMAILJS_SETUP.md | Contact form (EmailJS) setup |
| TESTING_GUIDE.md | Running and writing tests |
| TEST_COVERAGE.md | Test coverage reference |
| EXTRACTION_PIPELINE.md | Resume parsing pipeline deep-dive |
| EDGE_CASES_HANDLED.md | Known edge cases and how they are handled |
MIT — see LICENSE for details.
- Jake's Resume — inspiration for the Professional template design
- Groq — fast AI inference for content enhancement
- Google Gemini — AI fallback provider
- Sparticuz Chromium — serverless Chromium for PDF generation
- Supabase — auth and storage
Made with ❤️ by developers, for job seekers