SmartCV - AI Resume Analyzer

A FastAPI-based backend service for AI-powered resume analysis and job matching.

Project Structure

smartcv/
│
├── app/
│   ├── main.py              # FastAPI application entry point
│   ├── routes/
│   │   └── resume.py        # Resume-related API endpoints
│   ├── services/
│   │   └── parser.py        # Resume parsing service (placeholder)
│   └── models/
│       └── schema.py        # Pydantic models for API responses
│
├── uploads/                 # Temporary file storage (to be implemented)
├── requirements.txt         # Python dependencies
└── README.md               # This file

Features

Current Implementation (MVP)

• Health Check: Root endpoint for API status
• File Upload: Resume upload endpoint with validation
• Format Support: PDF and DOCX file validation
• Error Handling: Comprehensive error responses

Features Implemented

• AI-powered resume content analysis
• Skill extraction and matching
• ATS scoring algorithm (0-100)
• Keyword matching analysis
• AI feedback generation (Google GenAI)
• Resume text extraction (PDF/DOCX)
• Docker containerization

API Endpoints

Health Check

GET /

Returns API status and version information.

Service Health

GET /api/v1/health

Returns detailed service health and AI capability status.

Upload Resume

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

Upload a resume file (PDF/DOCX only).

Response:

{
  "file_path": "/app/uploads/resume.pdf",
  "original_filename": "resume.pdf",
  "extracted_text": "Resume content here...",
  "text_preview": "First 100 characters...",
  "text_length": 1500,
  "status": "success",
  "message": "Resume uploaded and parsed successfully"
}

Analyze Resume

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

Analyze resume against job description with ATS scoring and AI feedback.

Request:

{
  "resume_text": "Software Engineer with 5 years experience...",
  "job_description": "Looking for Python developer with AWS..."
}

Response:

{
  "score": 85,
  "matched_keywords": ["python", "aws", "react"],
  "missing_keywords": ["kubernetes", "docker"],
  "breakdown": {
    "keyword_match_score": 45.0,
    "technical_skill_score": 15.0,
    "length_score": 10.0,
    "frequency_score": 8.0
  },
  "insights": {
    "keyword_match_ratio": "8/10",
    "resume_length_words": 450,
    "recommendation": "Excellent match! Your resume strongly aligns..."
  },
  "feedback": {
    "strengths": ["Good technical alignment", "Relevant experience"],
    "weaknesses": ["Missing some key skills"],
    "suggestions": ["Add Kubernetes experience", "Quantify achievements"]
  }
}

Supported Formats

GET /api/v1/supported-formats

Returns list of supported file formats and size limits.

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Run the application:

uvicorn app.main:app --reload

The API will be available at http://localhost:8000

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Development Notes

Current Status

• ✅ Project structure setup
• ✅ Basic FastAPI application
• ✅ File upload endpoint
• ✅ Resume text extraction (PDF/DOCX)
• ✅ ATS scoring algorithm
• ✅ Keyword matching analysis
• ✅ AI feedback generation (Google GenAI)
• ✅ Docker containerization
• ✅ Environment variable support
• ✅ Health monitoring endpoints
• ✅ Docker Compose setup

Next Steps

1. Implement database storage
2. Add authentication
3. Create comprehensive tests
4. Create comprehensive tests

Tech Stack

• Framework: FastAPI
• Validation: Pydantic
• Server: Uvicorn
• File Handling: Python-multipart
• PDF Processing: pdfplumber
• DOCX Processing: python-docx
• AI Integration: Google GenAI SDK
• Containerization: Docker & Docker Compose
• Environment: python-dotenv
• Logging: RotatingFileHandler

Git Setup

Initial Setup

# Initialize Git repository
git init

# Add all files (excluding .gitignore patterns)
git add .

# Create initial commit
git commit -m "Initial commit: FastAPI resume parser MVP"

Important Notes

Why uploads/ should NOT be committed:

• Contains user-uploaded resume files with personal information
• Files are stored with UUID names but still contain sensitive data
• Directory can grow indefinitely and shouldn't be in version control
• Each deployment/environment should have its own uploads directory

Why venv/ should NOT be committed:

• Virtual environment is specific to your machine and Python version
• Contains binary files that aren't portable across systems
• Can be easily recreated with pip install -r requirements.txt
• Different developers may use different Python versions/OS

Recommended Git Workflow

# Create virtual environment (once per developer)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create uploads directory (if not exists)
mkdir -p uploads

# Run the application
uvicorn app.main:app --reload

.gitignore Best Practices

The included .gitignore file already excludes:

• Virtual environments (venv/, env/)
• Python cache files (__pycache__/, *.pyc)
• Upload directory (uploads/)
• IDE files (.vscode/, .idea/)
• OS files (.DS_Store, Thumbs.db)

Contributing

1. Follow the existing code structure
2. Add appropriate error handling
3. Include docstrings for new functions
4. Update API documentation
5. Test file uploads with different formats
6. Check logs for any issues

Docker Deployment

Prerequisites

• Docker installed on your system
• Google GenAI API key (optional, for AI feedback)

Quick Start

1. Configure Environment Variables

   cp .env.example .env
   # Edit .env with your Google GenAI API key

2. Build Docker Image

   docker build -t smartcv .

3. Run Container

   docker run -p 8000:8000 --env-file .env smartcv

Using Docker Compose (Recommended)

1. Configure Environment

   cp .env.example .env
   # Edit .env with your configuration

2. Run with Docker Compose

   docker-compose up -d

3. Stop Services

   docker-compose down

Container Features

• Health Checks: Automatic health monitoring on /health
• Volume Mounts: Persistent uploads and logs
• Environment Variables: Secure configuration
• Production Ready: Optimized for deployment

Accessing the API

Once running, access the API at:

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Upload Endpoint: http://localhost:8000/api/v1/upload-resume
• Analysis Endpoint: http://localhost:8000/api/v1/analyze-resume

Troubleshooting

Container Logs

# View logs
docker logs smartcv

# Follow logs in real-time
docker logs -f smartcv

Common Issues

• Ensure port 8000 is not already in use
• Check that .env file exists with proper API key
• Verify Docker daemon is running

Development with Docker

# Rebuild without cache
docker build --no-cache -t smartcv .

# Run in interactive mode
docker run -it -p 8000:8000 --env-file .env smartcv /bin/bash

License

MIT License