RoleFit is a sophisticated backend service that leverages AI to generate tailored resumes and cover letters based on job descriptions. It provides a comprehensive platform for managing user profiles, skills, experiences, and automatic document generation with intelligent content optimization.
- Overview
- Key Features
- Architecture
- Tech Stack
- Project Structure
- Setup & Installation
- Running the Application
- API Endpoints
- Core Modules
- Database Schema
- Async Processing with Celery
- Caching Strategy
- Configuration
- Development
RoleFit is a FastAPI-based backend service designed to help job seekers create customized resumes and cover letters. The platform intelligently analyzes job descriptions and generates optimized documents that match the job requirements while maintaining authenticity.
Job seekers spend considerable time manually tailoring their resumes for each job application. RoleFit automates this process using AI to:
- Parse and understand job descriptions
- Extract relevant user skills and experiences
- Generate customized, ATS-friendly resumes
- Create compelling cover letters tailored to specific jobs
- Manage multiple document versions
- User registration and authentication
- Secure JWT-based authorization
- User profile management with customizable settings
- Account authentication with email verification
- Multiple resume templates (Sidebar, Bold, Minimalist styles)
- Automatic resume generation from user profile data
- Resume extraction from uploaded PDF files
- Dynamic resume updates based on job descriptions
- PDF generation in multiple formats
- ATS-optimized resume structure
- AI-powered cover letter creation
- Multiple template styles (Minimal, Professional, Creative)
- Job description-based content generation
- Dynamic PDF generation with formatting
- Cover letter caching for performance
- Import and store job descriptions
- Automated JD parsing and analysis
- Skill and requirement extraction
- Support for multiple job descriptions per user
- Job description caching and search
The system manages comprehensive user profile information:
- Profile: Basic user information and preferences
- Experience: Work history with detailed descriptions
- Education: Academic qualifications and certifications
- Skills: Professional skills with proficiency levels
- Tools/Technologies: Technical tools and programming languages
- Projects: Portfolio projects with descriptions
- Publications: Research papers, articles, and publications
- Achievements: Certifications, awards, and recognitions
- AI-Powered Content Generation: Uses Groq AI for intelligent content synthesis
- Smart Filtering: Filters user data based on job requirements
- Caching Layer: Redis-based caching for performance optimization
- Real-time Updates: WebSocket support for live document generation status
- Async Processing: Celery for background task processing
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Web Server │
│ (Port 8000) │
└──────────────────┬──────────────────────────────────────────┘
│
┌──────────┼──────────┬──────────┐
│ │ │ │
┌───▼──┐ ┌───▼──┐ ┌───▼──┐ ┌───▼──┐
│Users │ │Resume│ │Cover │ │ Job │
│ │ │Letter│ │Letter│ │ Desc │
└───┬──┘ └───┬──┘ └───┬──┘ └───┬──┘
│ │ │ │
└─────────┼─────────┼─────────┘
│
┌─────────┼─────────┐
│ │ │
┌───▼──┐ ┌──▼──┐ ┌──▼──┐
│ DB │ │Redis│ │Celery
│(PgSQL) │Cache│ │Worker
└───────┘ └─────┘ └──────┘
- Client Request → FastAPI Router
- Authentication → JWT Validation
- Business Logic → Service Layer
- Data Access → Database/Cache
- Long Operations → Celery Queue
- Response → JSON Response or WebSocket Update
- FastAPI (0.135.2) - Modern async web framework
- Uvicorn - ASGI server
- Pydantic (2.12.5) - Data validation and settings management
- Python (3.9+)
- PostgreSQL (16-Alpine) - Primary database
- Redis (7-Alpine) - Caching layer and message broker
- SQLAlchemy - ORM for database operations
- Groq (1.2.0) - AI API for intelligent content generation
- PDFMiner.six (20251230) - PDF parsing and extraction
- pdfplumber (0.11.9) - PDF analysis
- Pillow (12.2.0) - Image processing for PDF generation
- Celery - Distributed task queue
- aioredis (2.0.1) - Async Redis client
- asyncio - Async runtime
- python-jose (3.5.0) - JWT token handling
- bcrypt (3.2.0) - Password hashing
- passlib (1.7.4) - Password utilities
- cryptography (47.0.0) - Encryption utilities
- python-dotenv - Environment configuration
- httpx - Async HTTP client
- email-validator - Email validation
- PyYAML - Configuration parsing
rolefit-backend/
├── app/
│ ├── api/
│ │ ├── router.py # Main API router
│ │ └── v1/ # API v1 endpoints
│ │ ├── auth/ # Authentication endpoints
│ │ ├── user/ # User management
│ │ ├── profile/ # User profile management
│ │ ├── resume/ # Resume generation endpoints
│ │ ├── cover_letter/ # Cover letter endpoints
│ │ ├── job_description/ # Job description endpoints
│ │ ├── experience/ # Work experience endpoints
│ │ ├── academics/ # Education endpoints
│ │ ├── skill/ # Skills management
│ │ ├── tools/ # Tools/technologies management
│ │ ├── project/ # Portfolio projects
│ │ ├── publications/ # Publications management
│ │ ├── resume_extractor/ # PDF resume extraction
│ │ ├── content/ # Content retrieval
│ │ ├── health/ # Health check endpoint
│ │ └── websocket/ # WebSocket connections
│ │
│ ├── core/
│ │ ├── AppError.py # Custom exception handling
│ │ ├── celery_app.py # Celery configuration
│ │ ├── cors.py # CORS setup
│ │ ├── logger.py # Logging configuration
│ │ ├── redis_keys.py # Redis key constants
│ │ ├── validation_error.py # Validation utilities
│ │ ├── expectations.py # Expectation validations
│ │ ├── grok_const.py # Groq AI constants
│ │ ├── sarvam_const.py # Sarvam AI constants
│ │ └── resume_colors.py # Resume styling constants
│ │
│ ├── db/
│ │ ├── db.py # SQLAlchemy setup
│ │ └── redis_db.py # Redis connection
│ │
│ ├── models/
│ │ ├── User.py # User model
│ │ ├── Profile.py # User profile model
│ │ ├── Experience.py # Work experience model
│ │ ├── Academic.py # Education model
│ │ ├── Skill.py # Skills model
│ │ ├── Tool.py # Tools/technologies model
│ │ ├── Project.py # Portfolio projects model
│ │ ├── Publication.py # Publications model
│ │ ├── Achievement.py # Achievements/certifications
│ │ ├── JobDescription.py # Job description model
│ │ ├── GeneratedDocument.py # Generated resumes/letters
│ │ ├── UserSkill.py # User-skill relationship
│ │ └── UserTool.py # User-tool relationship
│ │
│ ├── schema/
│ │ ├── auth.py # Authentication schemas
│ │ ├── pdf_resume.py # PDF resume schemas
│ │ ├── CoverLetterData.py # Cover letter data schemas
│ │ ├── Academic.py # Academic schemas
│ │ ├── Experience.py # Experience schemas
│ │ ├── Skill.py # Skill schemas
│ │ ├── Tool.py # Tool schemas
│ │ ├── Project.py # Project schemas
│ │ ├── Publication.py # Publication schemas
│ │ ├── JobDescription.py # Job description schemas
│ │ └── GeneratedDocument.py # Generated document schemas
│ │
│ ├── response/
│ │ ├── user_responses.py # User response schemas
│ │ ├── profile_responses.py # Profile response schemas
│ │ ├── experience_responses.py # Experience responses
│ │ ├── academic_responses.py # Academic responses
│ │ ├── skill_responses.py # Skill responses
│ │ ├── tool_responses.py # Tool responses
│ │ ├── project_responses.py # Project responses
│ │ ├── publication_responses.py # Publication responses
│ │ ├── GenerateDocument_responses.py # Document responses
│ │ └── job_description_response.py # Job description responses
│ │
│ ├── helpers/
│ │ ├── redis_cache_helpers.py # Redis caching utilities
│ │ ├── db_helpers.py # Database helper functions
│ │ ├── pdf_helpers.py # PDF generation utilities
│ │ ├── jd_parser.py # Job description parsing
│ │ ├── filter_jd.py # Job description filtering
│ │ ├── filter_jd_sync.py # Sync JD filtering
│ │ ├── resume_prompt.py # Resume generation prompts
│ │ ├── cover_letter_prompt.py # Cover letter prompts
│ │ ├── build_pdf.py # Base PDF builder
│ │ ├── build_pdf_bold.py # Bold resume template
│ │ ├── build_pdf_minimalist.py # Minimalist resume template
│ │ ├── build_pdf_sidebar.py # Sidebar resume template
│ │ ├── build_cover_letter_pdf.py # Cover letter PDF builder
│ │ ├── build_cover_letter_bold.py # Bold cover letter template
│ │ ├── build_cover_letter_minimal.py # Minimal cover letter template
│ │ ├── celery_helpers.py # Celery task helpers
│ │ ├── grok_ai_headers.py # Groq API headers
│ │ ├── sarvam_ai_headers.py # Sarvam API headers
│ │ └── validation_schemas.py # Data validation
│ │
│ ├── dependency/
│ │ └── dependencies.py # FastAPI dependency injection
│ │
│ ├── tasks/
│ │ └── [Celery async tasks] # Background job tasks
│ │
│ ├── utils/
│ │ └── [Utility functions] # General utilities
│ │
│ ├── validators/
│ │ └── [Data validators] # Validation logic
│ │
│ └── websockets/
│ ├── redis_subscriber.py # Redis WebSocket subscriber
│ └── [WebSocket handlers] # Real-time communication
│
├── docker/
│ └── init.sql/ # Database initialization scripts
│
├── logs/ # Application logs
│
├── tests/ # Test suite
│ ├── test_resume_generation.py
│ ├── test_enum_parsing.py
│ ├── test_requirements.txt
│ └── ...
│
├── env/ # Python virtual environment
│
├── main.py # Application entry point
├── requirements.txt # Python dependencies
├── docker-compose.yml # Docker compose configuration
├── Dockerfile # Docker image build
├── run_celery_worker.py # Celery worker runner
├── run_celery_beat.py # Celery beat scheduler runner
└── debug_celery.py # Celery debugging script
- Python 3.9 or higher
- Docker and Docker Compose (for containerized setup)
- PostgreSQL 16 (if not using Docker)
- Redis 7 (if not using Docker)
- Git
git clone https://github.com/yourusername/rolefit.git
cd rolefit/rolefit-backendpython -m venv env
source env/bin/activate # On Windows: env\Scripts\activatepip install -r requirements.txtCreate a .env file in the rolefit-backend directory:
# Database
DATABASE_URL=postgresql://rolefit:secret@localhost:5432/rolefit
# Redis
REDIS_URL=redis://localhost:6379
# JWT
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
# AI APIs
GROQ_API_KEY=your-groq-api-key
GROQ_MODEL=mixtral-8x7b-32768
# Email (if needed)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
# Celery
CELERY_BROKER_URL=redis://localhost:6379
CELERY_RESULT_BACKEND=redis://localhost:6379
# Application
APP_NAME=RoleFit
DEBUG=True# Ensure PostgreSQL is running
psql -U rolefit -d rolefit -f docker/init.sql/init.sqluvicorn main:app --reload --host 0.0.0.0 --port 8000cd rolefit
docker-compose up -dThis will start:
- Backend API (http://localhost:8000)
- PostgreSQL Database (localhost:5432)
- Redis Cache (localhost:6379)
- Celery Worker (background tasks)
docker-compose logs -f backend
docker-compose logs -f celery-worker
docker-compose logs -f postgresdocker-compose down# Standard run
uvicorn main:app --reload
# With specific host and port
uvicorn main:app --host 0.0.0.0 --port 8000 --reloadpython run_celery_worker.py
# or
celery -A app.core.celery_app worker -l infopython run_celery_beat.py
# or
celery -A app.core.celery_app beat -l info- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json
POST /signup- Register new userPOST /login- User login with email/passwordPOST /refresh-token- Refresh JWT tokenPOST /logout- User logout
GET /- Get current user profileGET /{user_id}- Get user by IDPUT /{user_id}- Update user informationDELETE /{user_id}- Delete user account
GET /- Get user profilePOST /- Create profilePUT /- Update profileDELETE /- Delete profile
GET /- Get all resumesPOST /generate- Generate resume from profilePOST /generate-tailored- Generate tailored resume for jobGET /{resume_id}/download- Download resume as PDFPUT /{resume_id}- Update resumeDELETE /{resume_id}- Delete resume
GET /- Get all cover lettersPOST /generate- Generate cover letterGET /{letter_id}/download- Download cover letter as PDFPUT /{letter_id}- Update cover letterDELETE /{letter_id}- Delete cover letter
GET /- Get all job descriptionsPOST /- Create/import job descriptionGET /{jd_id}- Get specific job descriptionPUT /{jd_id}- Update job descriptionDELETE /{jd_id}- Delete job descriptionPOST /parse- Parse and extract job requirements
GET /- Get all work experiencesPOST /- Add new experiencePUT /{exp_id}- Update experienceDELETE /{exp_id}- Delete experience
GET /- Get all education recordsPOST /- Add new educationPUT /{academic_id}- Update educationDELETE /{academic_id}- Delete education
GET /- Get all skillsPOST /- Add skillPUT /{skill_id}- Update skillDELETE /{skill_id}- Delete skill
GET /- Get all toolsPOST /- Add toolPUT /{tool_id}- Update toolDELETE /{tool_id}- Delete tool
GET /- Get all projectsPOST /- Add projectPUT /{project_id}- Update projectDELETE /{project_id}- Delete project
GET /- Get all publicationsPOST /- Add publicationPUT /{pub_id}- Update publicationDELETE /{pub_id}- Delete publication
POST /upload- Upload and extract resume from PDFGET /status/{task_id}- Check extraction status
GET /{content_id}- Get generated content (resume/cover letter)
GET /- Check API health status
WS /connect- Connect to real-time updates
Handles user authentication, JWT token generation, and password management.
- Email/password registration
- JWT-based authentication
- Secure password hashing with bcrypt
- Token refresh mechanism
Core functionality for resume creation and customization.
-
Features:
- Multiple resume templates (Sidebar, Bold, Minimalist)
- Smart resume tailoring based on job descriptions
- ATS-optimized formatting
- Real-time PDF generation
- Version control and storage
-
Templates:
- Bold: Professional template with emphasis on achievements
- Sidebar: Modern template with sidebar for quick info
- Minimalist: Clean and simple design
Automated cover letter creation with AI assistance.
-
Features:
- AI-powered content generation using Groq
- Multiple writing styles
- Job description matching
- PDF generation with professional formatting
- Caching for performance
-
Templates:
- Minimal: Concise professional format
- Bold: Emphasizes achievements
- Creative: Personalized and engaging style
Intelligent parsing and analysis of job descriptions.
- Features:
- Automatic skill extraction
- Requirement analysis
- Keyword identification
- Salary range extraction
- Technology stack detection
Automated resume parsing from PDF files.
- Features:
- PDF parsing and text extraction
- Information structuring
- Automatic field detection
- Data validation
- Error handling for malformed PDFs
Redis-based caching for performance optimization.
- Features:
- User authentication cache
- Resume cache
- Job description cache
- Cover letter cache
- Configurable TTL (Time To Live)
id: UUID (Primary Key)
email: String (Unique)
password_hash: String
created_at: Timestamp
updated_at: Timestamp
is_active: Boolean
is_verified: Boolean
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
first_name: String
last_name: String
phone: String
location: String
headline: String
summary: String
profile_picture_url: String
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
job_title: String
company: String
employment_type: String
start_date: Date
end_date: Date (nullable)
description: Text
is_current: Boolean
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
school: String
degree: String
field_of_study: String
start_date: Date
end_date: Date
grade: String (nullable)
activities: Text (nullable)
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
skill_name: String
proficiency_level: Enum (Beginner, Intermediate, Advanced, Expert)
endorsements: Integer (default: 0)
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
tool_name: String
experience_level: String
years_of_experience: Integer
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
project_name: String
description: Text
technologies_used: String[] (array)
start_date: Date
end_date: Date (nullable)
project_url: String (nullable)
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
job_title: String
company: String
job_description: Text
required_skills: String[] (array)
preferred_skills: String[] (array)
imported_at: Timestamp
saved_at: Timestamp
id: UUID (Primary Key)
user_id: UUID (Foreign Key)
job_description_id: UUID (Foreign Key, nullable)
document_type: Enum (Resume, CoverLetter)
template_type: String
content_json: JSON
generated_at: Timestamp
file_path: String
status: Enum (Processing, Completed, Failed)
Celery is a distributed task queue that allows the application to execute long-running operations asynchronously.
-
Resume PDF Generation
- Generates resume PDF in background
- Notifies user via WebSocket when complete
- Stores file for download
-
Cover Letter PDF Generation
- Generates cover letter PDF asynchronously
- Supports multiple templates
- Real-time progress updates
-
Resume Extraction from PDF
- Parses uploaded resume files
- Extracts and structures information
- Validates extracted data
-
Job Description Parsing
- Parses job postings
- Extracts skills and requirements
- Identifies key technologies
# Start worker
python run_celery_worker.py
# Start scheduler (for periodic tasks)
python run_celery_beat.py
# Monitor tasks (in another terminal)
celery -A app.core.celery_app eventsThe application uses Redis for caching with the following strategy:
-
Authentication Cache
- Cache authenticated user objects
- TTL: 30 minutes
- Invalidated on logout or password change
-
User Data Cache
- Cache user profile, skills, experiences
- TTL: 15 minutes
- Invalidated on profile update
-
Job Description Cache
- Cache parsed job descriptions
- TTL: 1 hour
- Invalidated on JD update
-
Resume/Cover Letter Cache
- Cache generated documents
- TTL: 2 hours
- Invalidated on content update
# Get cached value
value = await get_cache(key)
# Set cached value with TTL
await set_cache(key, value, ttl=300)
# Delete cached value
await delete_cache(key)
# Invalidate user cache
await invalidate_user_cache(user_id)Create a .env file with the following variables:
# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/rolefit
# Redis Configuration
REDIS_URL=redis://localhost:6379
# JWT Configuration
SECRET_KEY=your-super-secret-key-change-this
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
# Groq AI Configuration
GROQ_API_KEY=your-groq-api-key
GROQ_MODEL=mixtral-8x7b-32768
# Application Settings
APP_NAME=RoleFit
DEBUG=False
LOG_LEVEL=INFO
# Celery Configuration
CELERY_BROKER_URL=redis://localhost:6379
CELERY_RESULT_BACKEND=redis://localhost:6379Key configuration files:
app/core/celery_app.py- Celery configurationapp/core/cors.py- CORS policy setupapp/core/logger.py- Logging configurationapp/db/db.py- Database configuration
# Run all tests
pytest
# Run specific test file
pytest tests/test_resume_generation.py
# Run with coverage
pytest --cov=app tests/- Service Layer: Business logic in
*_service.pyfiles - Router Layer: API endpoints in
*_router.pyfiles - Schema Layer: Data validation in
schema/directory - Response Layer: Response formatting in
response/directory - Models: Database models in
models/directory
- Create model in
app/models/ - Create schema in
app/schema/ - Create response schema in
app/response/ - Create service in
app/api/v1/[feature]/ - Create router in
app/api/v1/[feature]/ - Add route to
app/api/v1/router.py
Enable debug logging:
DEBUG=True
LOG_LEVEL=DEBUGView logs:
# Docker logs
docker-compose logs -f backend
# Local logs
tail -f logs/app.log- Database Queries: Use efficient queries with proper indexing
- Caching: Leverage Redis for frequently accessed data
- PDF Generation: Offload to Celery workers
- File Storage: Store PDFs efficiently with proper cleanup
- API Rate Limiting: Consider implementing rate limits for public endpoints
- JWT Authentication: Secure token-based authentication
- Password Hashing: bcrypt with salt for password security
- CORS: Configurable CORS policy
- SQL Injection Prevention: SQLAlchemy ORM prevents SQL injection
- Input Validation: Pydantic schema validation on all inputs
- Error Handling: Custom error handlers prevent information leakage
{
"status": "success",
"data": {
"id": "uuid",
"name": "John Doe"
}
}{
"status": "error",
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message"
}
}- Create feature branch:
git checkout -b feature/feature-name - Commit changes:
git commit -m "Add feature" - Push to branch:
git push origin feature/feature-name - Create Pull Request
[Your License Here]
For issues and questions:
- Create an issue on GitHub
- Contact: support@rolefit.com
- Set
DEBUG=False - Update
SECRET_KEYwith strong random value - Configure production database
- Configure production Redis instance
- Set up SSL/TLS certificates
- Configure proper CORS origins
- Set up logging and monitoring
- Configure backup strategy
- Set up CI/CD pipeline
- Load test the application
- API Server: AWS ECS, Google Cloud Run, or Heroku
- Database: AWS RDS PostgreSQL
- Cache: AWS ElastiCache Redis
- File Storage: AWS S3
- Task Queue: Celery with managed Redis
- FastAPI Documentation
- PostgreSQL Documentation
- Redis Documentation
- Celery Documentation
- Pydantic Documentation
Version: 1.0.0
Last Updated: May 2026
Maintainer: RoleFit Team