• What's New
• Features
• Demo
• Architecture
• Tech Stack
• Getting Started
  • Prerequisites
  • Backend Setup
  • Frontend Setup
• Project Structure
• API Documentation
• Security
• Deployment
• Documentation
• Contributing
• License
• Contact

🎯 ATS Optimization

• Advanced keyword extraction and density analysis
• ATS compatibility validation (95%+ scores)
• Job description keyword matching
• STAR methodology for experience bullets

📄 Multiple Export Formats

• Markdown download (optimized content)
• PDF generation (ATS-friendly templates)
• DOCX generation (editable Word documents)
• RenderCV integration for professional templates

🔍 Enhanced Analysis

• Keyword matching visualization
• Dynamic section filtering based on job description
• Improved strengths/weaknesses analysis
• Actionable suggestions with specific improvements

🛠️ New Backend Services

• ats_validator.py - ATS compatibility checking
• keyword_analyzer.py - Advanced keyword analysis
• docx_generator.py - DOCX file generation
• section_filter.py - Smart section filtering
• rendercv_generator.py - Professional template rendering

📚 Documentation

• Comprehensive setup guides in docs/setup/
• ATS implementation guides
• API documentation
• Project status tracking
• Migration guides for RenderCV

See full changelog: CHANGELOG.md

• 📤 Drag & Drop Upload: Easy file upload with support for PDF, Markdown, and Text
• 🤖 AI Analysis: Comprehensive CV analysis with actionable insights
• 📊 ATS Scoring: Detailed compatibility metrics for Applicant Tracking Systems
• ✨ Professional Templates: Clean, ATS-friendly resume designs
• 🎨 Live Preview: Real-time preview of optimized resume
• 💾 Multiple Formats: Download as Markdown, PDF, or DOCX
• 🔍 Keyword Analysis: Match job description keywords with CV content
• ⚡ Dynamic Filtering: Show/hide CV sections based on relevance

graph TB
    A[User] -->|Upload CV| B[Frontend - React + Vite]
    B -->|API Request| C[Backend - FastAPI]
    C -->|Store| D[MongoDB Atlas]
    C -->|Analyze| E[spaCy NLP]
    C -->|Optimize| F[AI - Gemini/OpenRouter]
    C -->|Validate| G[Security Scanner]
    F -->|Optimized CV| C
    C -->|Response| B
    B -->|Display| A

Frontend (React + TypeScript + Vite)

• Modern React 19 with TypeScript for type safety
• Vite for lightning-fast development and builds
• TailwindCSS for responsive, utility-first styling
• shadcn/ui for beautiful, accessible components
• Framer Motion for smooth animations

Backend (FastAPI + Python)

• Async FastAPI for high-performance API
• spaCy for advanced NLP and entity extraction
• MongoDB Atlas for scalable cloud database
• Multi-AI support (Gemini & OpenRouter)
• WeasyPrint for server-side PDF generation

Before you begin, ensure you have the following installed:

• Python 3.11+ (Download)
• Node.js 18+ (Download)
• MongoDB Atlas Account (Sign Up - Free M0 tier)
• OpenRouter API Key (Get Key - Free tier available)
• Optional: Google Gemini API Key (Get Key - Alternative AI provider)

1. Clone the repository

git clone https://github.com/mu7ammad-3li/cv-lize.git
cd cv-lize/backend

2. Create virtual environment

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

3. Install dependencies

    pip install -r requirements.txt

4. Download spaCy model

python -m spacy download en_core_web_sm

5. Configure environment variables

Create .env file in backend/ directory:

# MongoDB Atlas
MONGODB_URI=mongodb+srv://username:[email protected]/cvlize?retryWrites=true&w=majority

# OpenRouter AI
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Google Gemini (Optional - alternative to OpenRouter)
GEMINI_API_KEY=your-gemini-api-key

# Application
ENVIRONMENT=development
DEBUG=True
PORT=8000
HOST=0.0.0.0

# CORS
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# File Upload
MAX_FILE_SIZE=5242880
UPLOAD_DIR=./uploads
QUARANTINE_DIR=./quarantine

# Rate Limiting
RATE_LIMIT_PER_MINUTE=10
RATE_LIMIT_WINDOW=900

# Session
SESSION_TTL_HOURS=24

6. Run the backend server

# Development
python main.py

# Or with uvicorn
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend will be running at: http://localhost:8000

API Documentation: http://localhost:8000/docs

1. Navigate to frontend directory

cd frontend

2. Install dependencies

npm install

3. Configure environment (optional)

Create .env file in frontend/ directory:

VITE_API_URL=http://localhost:8000

4. Run development server

npm run dev

Frontend will be running at: http://localhost:5173

5. Build for production

npm run build

cv-lize/
├── 📂 backend/                      # FastAPI Backend
│   ├── main.py                      # Application entry point
│   ├── requirements.txt             # Python dependencies
│   ├── .env                         # Environment variables (create this)
│   ├── .env.example                 # Environment template
│   ├── Dockerfile                   # Docker configuration
│   ├── API_DOCUMENTATION.md         # API documentation
│   ├── 📂 routes/                   # API endpoints
│   │   ├── upload.py               # CV upload endpoint
│   │   ├── analyze.py              # AI analysis endpoint
│   │   └── download.py             # Download endpoints (MD, PDF, DOCX)
│   ├── 📂 services/                 # Business logic
│   │   ├── nlp_processor.py        # spaCy CV parsing
│   │   ├── gemini_service.py       # Google Gemini AI (optional)
│   │   ├── openrouter_service.py   # OpenRouter AI (primary)
│   │   ├── ats_validator.py        # ATS compatibility validation
│   │   ├── keyword_analyzer.py     # Keyword extraction & analysis
│   │   ├── section_filter.py       # Dynamic section filtering
│   │   ├── markdown_parser.py      # Markdown processing
│   │   ├── pdf_generator.py        # PDF generation
│   │   ├── docx_generator.py       # DOCX generation
│   │   ├── rendercv_generator.py   # RenderCV integration
│   │   └── rendercv_transformer.py # CV data transformation
│   ├── 📂 models/                   # Data models
│   │   ├── schemas.py              # Pydantic schemas
│   │   └── database.py             # MongoDB connection
│   ├── 📂 middleware/               # Middleware
│   │   └── rate_limit.py           # Rate limiting
│   ├── 📂 utils/                    # Utilities
│   │   └── pdf_validator.py        # Security validation
│   └── 📂 templates/                # PDF templates
│       ├── professional.html        # Professional template
│       └── professional_structured_v2.html  # ATS-optimized template
├── 📂 frontend/                     # React Frontend
│   ├── 📂 src/
│   │   ├── App.tsx                 # Main application
│   │   ├── main.tsx                # Entry point
│   │   ├── index.css               # Global styles
│   │   ├── 📂 components/          # React components
│   │   │   ├── HomePage.tsx        # Landing page
│   │   │   ├── FileUpload.tsx      # Drag-drop upload
│   │   │   ├── CVAnalysis.tsx      # Analysis display
│   │   │   ├── ProfessionalTemplate.tsx  # Resume template
│   │   │   └── 📂 ui/              # shadcn/ui components
│   │   ├── 📂 lib/                 # Utilities
│   │   │   ├── api.ts              # API client
│   │   │   └── utils.ts            # Helper functions
│   │   └── 📂 templates/           # Additional templates
│   ├── package.json                # Node dependencies
│   ├── vite.config.ts              # Vite configuration
│   ├── tailwind.config.js          # Tailwind configuration
│   └── tsconfig.json               # TypeScript configuration
├── 📂 docs/                        # Documentation
│   ├── 📂 images/                  # Main images
│   │   └── screenshot.png          # Hero screenshot
│   ├── 📂 screenshots/             # Application screenshots
│   │   ├── cv-lize-upload-interface.png
│   │   ├── cv-lize-ats-scoring.png
│   │   ├── cv-lize-analysis-view.png
│   │   └── cv-lize-full-analysis-result.png
│   ├── 📂 setup/                   # Setup guides
│   │   ├── INSTALLATION_GUIDE.md   # Installation instructions
│   │   ├── SETUP.md                # Quick setup guide
│   │   ├── DEPLOYMENT.md           # Deployment guides
│   │   ├── FREE_DEPLOYMENT.md      # Free deployment options
│   │   ├── AWS_DEPLOYMENT.md       # AWS deployment guide
│   │   ├── GIT_SETUP.md            # Git configuration
│   │   └── GITIGNORE_GUIDE.md      # Gitignore documentation
│   ├── 📂 project-status/          # Project status documents
│   │   ├── PROJECT_COMPLETE.md     # Project completion status
│   │   ├── BACKEND_COMPLETE.md     # Backend completion status
│   │   ├── IMPLEMENTATION_STATUS.md # Implementation details
│   │   ├── TESTING_COMPLETE.md     # Testing status
│   │   ├── STATUS.md               # Overall status
│   │   └── SYSTEM_STATUS.md        # System status
│   ├── 📂 development/             # Development docs
│   │   └── ATS_SYSTEM_PROMPT.md    # ATS optimization prompts
│   ├── 📂 migration/               # Migration guides
│   │   └── RENDERCV_MIGRATION.md   # RenderCV migration
│   ├── ATS_IMPLEMENTATION.md       # ATS feature implementation
│   ├── ATS_RECOMMENDATIONS.md      # ATS best practices
│   ├── DYNAMIC_SECTIONS_FEATURE.md # Dynamic sections feature
│   ├── INTEGRATION_GUIDE.md        # Integration documentation
│   └── CHANGELOG.md                # Project changelog
├── .gitignore                      # Git ignore rules
├── CHANGELOG.md                    # Changelog (root copy)
├── README.md                       # This file
└── LICENSE                         # MIT License

http://localhost:8000

POST /api/upload
Content-Type: multipart/form-data

Parameters:
- file: File (PDF, Markdown, or Text)

Response: 200 OK
{
  "session_id": "uuid-v4",
  "filename": "john_doe_cv.pdf",
  "file_hash": "sha256...",
  "file_type": "pdf",
  "extracted_text": "...",
  "parsed_data": {
    "skills": ["Python", "FastAPI", "React"],
    "experience": [...],
    "education": [...],
    "contact": {...}
  }
}

POST /api/analyze
Content-Type: application/json

Body:
{
  "session_id": "uuid-v4",
  "job_description": "We are seeking a Full Stack Developer..."
}

Response: 200 OK
{
  "analysis": {
    "score": 85,
    "ats_compatibility": 92,
    "match_percentage": 78,
    "strengths": ["Strong technical skills", ...],
    "weaknesses": ["Limited management experience", ...],
    "suggestions": ["Add cloud certifications", ...]
  },
  "optimized_cv": {
    "markdown": "# Full Name\n\n## Professional Summary\n..."
  },
  "parsed_resume": {
    "personalInfo": {...},
    "sections": [...]
  }
}

GET /api/download/{session_id}/markdown
GET /api/download/{session_id}/pdf

Response: File download

GET /health

Response: 200 OK
{
  "status": "healthy",
  "database": "connected"
}

Visit http://localhost:8000/docs for Swagger UI interactive documentation.

CV-lize implements enterprise-grade security measures:

✅ Magic Byte Verification - Validates actual file type
✅ Size Limits - Maximum 5MB per file
✅ Format Validation - Only PDF, Markdown, and Text allowed

✅ Embedded JavaScript - Detects XSS attempts
✅ Executable Files - Blocks PE/ELF/Mach-O binaries
✅ Remote File Redirects - Prevents SMB attacks
✅ XFA Forms - Detects XXE vulnerabilities

✅ Bash Reverse Shells - bash -i >& /dev/tcp/
✅ Python Sockets - socket.socket()
✅ Netcat/Socat - Common backdoor patterns
✅ PowerShell TCP - System.Net.Sockets.TCPClient
✅ Ruby/Perl Shells - Various reverse shell patterns

✅ Rate Limiting - 50 requests/hour per IP
✅ CORS Protection - Whitelist-based origins
✅ Input Sanitization - All user inputs sanitized
✅ Session Management - 24-hour TTL with auto-cleanup
✅ File Quarantine - Suspicious files isolated with SHA-256 logging

cd frontend
vercel

cd backend
# Connect GitHub repo

# See AWS guide

Backend:

MONGODB_URI=mongodb+srv://...
OPENROUTER_API_KEY=sk-or-v1-...
ALLOWED_ORIGINS=https://your-frontend.vercel.app
ENVIRONMENT=production
DEBUG=False

Frontend:

VITE_API_URL=https://your-backend.render.com

For detailed deployment instructions, see:

• Free Deployment Guide - Vercel + Render (100% Free)
• AWS Deployment Guide - AWS Free Tier
• General Deployment - All options

Comprehensive documentation is available in the docs/ directory:

• Installation Guide - Detailed installation instructions
• Quick Setup - Fast setup guide
• Git Setup - Git configuration
• Gitignore Guide - Git ignore patterns

• Free Deployment - Deploy for free (Vercel + Render)
• AWS Deployment - AWS EC2 + MongoDB Atlas
• General Deployment - All deployment options

• ATS Implementation - ATS optimization features
• ATS Recommendations - ATS best practices
• Dynamic Sections - Dynamic section filtering
• Integration Guide - Integration documentation
• API Documentation - Backend API reference

• ATS System Prompt - AI optimization prompts
• RenderCV Migration - RenderCV integration guide

• Project Complete - Overall completion status
• Backend Complete - Backend status
• Implementation Status - Feature implementation
• Testing Complete - Testing status
• System Status - System overview

• CHANGELOG.md - Version history and changes

Contributions are what make the open-source community amazing! Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

• Follow existing code style
• Write clear commit messages
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

This project follows the Contributor Covenant Code of Conduct.

Distributed under the MIT License. See LICENSE for more information.

Muhammad Ali

• GitHub: @mu7ammad-3li
• Email: [email protected]
• LinkedIn: linkedin.com/in/muhammad-3lii

Project Link: https://github.com/mu7ammad-3li/cv-lize

• FastAPI - Modern Python web framework
• React - UI library
• shadcn/ui - Beautiful component library
• spaCy - Advanced NLP
• OpenRouter - AI gateway and API
• NVIDIA Nemotron - AI language model
• Google Gemini - Alternative AI analysis
• MongoDB Atlas - Cloud database
• RenderCV - Professional CV templates
• Vercel - Frontend deployment
• Render - Backend deployment

If you find this project helpful, please consider giving it a star!