Skip to content

README.md

Latest commit

 

History

History
232 lines (174 loc) · 11.7 KB

README.md

File metadata and controls

232 lines (174 loc) · 11.7 KB
Raw

📄 Naphix Resume — Visual A4 Resume Builder

React TypeScript Tailwind CSS Vite Gemini AI License

A privacy-first, visual A4 resume builder featuring real-time live preview, universal custom sections, drag-and-drop ordering, client-side PDF/DOCX importing, dual ATS-compliant exports, and AI-powered Job Match analysis.

🌐 Live Production Website • 👨‍💻 Developer Portfolio • 🐙 GitHub Repository

🌟 Overview

Naphix Resume is a modern, developer-focused resume builder that treats your resume as a genuine ISO 216 A4 (210 × 297mm) document. Instead of filling out disconnected forms and guessing the final layout, the editor features an interactive split-screen workspace with instantaneous live preview synchronization.

All resume drafting, editing, and file importing operate 100% on the client side with browser localStorage, ensuring complete privacy without requiring an account, sign-up, or tracking.

For job seekers optimizing applications, an integrated server-proxied Job Match feature analyzes candidate resumes against target job descriptions using Google Gemini AI, returning compatibility scores, requirement matching, and tailored suggestions.

✨ Main Features

  • ⚡ Real-Time Live A4 Preview: Instantaneous typographic feedback on an authentic EB Garamond single-page canvas.
  • 🔄 Drag-and-Drop Reordering: Smooth drag-and-drop section and entry reordering powered by @dnd-kit with touch and pointer sensors.
  • 🧩 Universal Custom Section Engine: Create custom sections (Awards, Certifications, Publications, Volunteer Experience, Leadership, etc.) with flexible field schemas.
  • 📥 Universal Resume Importer: 10-stage client-side parser that extracts text and structure from existing PDF and Word (.docx) resumes with multi-column reconstruction and 4-factor confidence scoring.
  • 🤖 Gemini AI Job Match: Evaluate your resume against target job postings to receive ATS match scores, requirement breakdowns, experience gaps, and improvement tips.
  • 📄 Dual High-Fidelity Exporters:
    • Vector PDF: Searchable, ATS-compliant single-page A4 PDF generated via @react-pdf/renderer.
    • Native Word DOCX: Native Microsoft Word document with right-aligned tab stops and bullet indentations generated via docx.
  • 📱 Fully Responsive Design: Desktop split-screen, tablet adaptive switcher, and mobile touch layout.
  • 🔒 100% Private & Local: Zero accounts, zero database storage. All resume data remains in your local browser storage.
  • ⏪ Undo / Redo History: Full 50-step state history with keyboard shortcuts (Ctrl+Z / Ctrl+Y).
  • 🚀 Complete SEO & Privacy: Pre-rendered landing page metadata, Schema.org JSON-LD structured data, and dynamic noindex protection on private editor routes.

🛠️ Tech Stack

Frontend & Core

Document Engines & Parsing

Backend, Security & AI

  • Runtime: Node.js Connect Middleware via Vite Plugin
  • AI Model: Google Gemini API (gemini-3.5-flash via @google/genai 2.17)
  • Security Middleware: In-memory sliding window rate limiter, IP concurrency guard, payload boundary validator, SHA-256 request fingerprinting cache, and quota circuit breaker.

📁 Project Structure

resumebuilder/
├── public/                       # Static public assets
│   ├── landing/screenshots/      # High-resolution showcase & OG images
│   ├── robots.txt                # Search engine crawler rules
│   └── sitemap.xml               # Canonical XML sitemap
├── src/
│   ├── components/               # React UI components
│   │   ├── editor/               # Resume section accordion forms & custom section modal
│   │   ├── export/               # Vector PDF & Word DOCX download modal
│   │   ├── importer/             # Universal Resume Importer modal & staged review
│   │   ├── jobMatch/             # Gemini Job Match dialog & score visualization
│   │   ├── preview/              # Live A4 document canvas & zoom toolbar
│   │   └── ui/                   # Reusable UI primitives (Button, Modal, Input)
│   ├── features/                 # Domain-driven feature logic
│   │   ├── importer/             # 10-stage document extraction & parsing engine
│   │   ├── jobMatch/             # Client API & Zustand store for Job Match
│   │   └── resume/               # Core data models, Zustand store, history, utilities
│   ├── landing/                  # Public marketing landing page & section components
│   ├── seo/                      # Centralized SEO config, JSON-LD, and usePageSeo hook
│   ├── templates/                # Resume layout templates (Developer Standard)
│   ├── App.tsx                   # Client-side router ('/' landing & '/editor')
│   └── main.tsx                  # React entry point
├── server/                       # Backend API & Security Layer
│   ├── config.ts                 # Security limits, model configuration, and TTL settings
│   ├── jobMatchApiHandler.ts     # HTTP pipeline with security headers & request tracking
│   ├── jobMatchService.ts        # Server-side Gemini service with injection defenses
│   └── security/                 # Rate limiter, cache, circuit breaker, input validator
├── scripts/                      # Automated validation & test suites
│   ├── test_seo.ts               # 47-point SEO and metadata test suite
│   ├── test_job_match_security.ts# 41-case security & rate limiting test suite
│   ├── test_job_match.ts         # Job Match API & schema audit suite
│   └── test_universal_importer_comprehensive.ts # 35-case importer corpus suite
├── docs/                         # In-depth technical documentation
├── AI_USAGE.md                   # Transparent AI-assisted development log
├── index.html                    # Root HTML with SEO metadata and structured data
└── package.json                  # Dependencies and scripts

🚀 Getting Started

Prerequisites

  • Node.js (v18.0.0 or higher recommended)
  • npm (bundled with Node.js)

Installation

  1. Clone the Repository:

    git clone https://github.com/naphiertech/resumebuilder.git
cd resumebuilder

  2. Install Dependencies:

    npm install

  3. Configure Environment Variables: Copy .env.example to .env:

    cp .env.example .env

  4. Start the Development Server:

    npm run dev

    Open your browser at http://localhost:5173/.

🔑 Environment Variables

Create a .env file in the root directory:

# Server-side Google Gemini API Key for Job Match
GEMINI_API_KEY=your_actual_gemini_api_key_here

# Pinned Gemini Model (Default: gemini-3.5-flash)
GEMINI_MODEL=gemini-3.5-flash

# Production Canonical Site URL (Used for SEO, canonical links, and Open Graph)
VITE_SITE_URL=https://naphix-resume.netlify.app
Variable Description Required
GEMINI_API_KEY Secret key for Google Gemini AI. Stored strictly server-side. For Job Match
GEMINI_MODEL Pinned model identifier (gemini-3.5-flash). No
VITE_SITE_URL Canonical URL for SEO metadata, Open Graph, and sitemaps. Yes

🧪 Testing & Quality Assurance

Run the automated test suites locally:

# 1. SEO & Structured Data Validation (47 tests)
npx tsx scripts/test_seo.ts

# 2. Job Match Security & Rate Limiting (41 tests)
npx tsx scripts/test_job_match_security.ts

# 3. Gemini Job Match & Schema Audit (22 tests)
npx tsx scripts/test_job_match.ts

# 4. Universal Resume Importer Comprehensive Corpus (43 tests across 35 documents)
npx tsx scripts/test_universal_importer_comprehensive.ts

# 5. Production TypeScript Compilation & Build
npm run build

📚 Technical Documentation Index

For detailed architectural specifications and design guides, explore the documentation:

  • 🏛️ System Architecture: High-level overview, layers, data flow diagrams, state management, and security boundaries.
  • 🧩 Application Features: In-depth documentation of all user-facing features and workflows.
  • 📥 Universal Resume Importer: 10-stage deterministic parsing engine, layout reconstruction, and 4-factor confidence scoring.
  • 🤖 AI Job Match System: Google Gemini integration, multi-tier security hardening, rate limiting, and caching.
  • 📄 Document Export Subsystem: Vector PDF (@react-pdf/renderer) and native Word DOCX (docx) compilation specifications.
  • 💻 Developer Guide: Local workflows, coding conventions, project scripts, and testing procedures.
  • 🚀 Deployment & Hosting: Production deployment architecture, environment variables, and Netlify hosting setup.
  • 📋 Architecture Decision Records: Historical ADRs documenting key technical choices and tradeoffs.
  • 🤖 AI Usage Log: Transparent log of AI-assisted engineering, tooling, and milestones.

📊 Project Status

  • Status: Production Ready & Fully Maintained
  • Live Deployment: https://naphix-resume.netlify.app/
  • Test Suite Status: 100% Passing (153/153 automated test cases)
  • Zero Database / Zero Tracking: 100% Client-side resume persistence

👨‍💻 Author & Connect

Created with passion by Naphier Awalie.

📄 License

This project is open-source and available under the MIT License.