Anurag.Jangid/Hire-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Hire-ai/README.md
AnuragJangid18 7a72438fd1 first commit
2026-10-08 02:50:35 +05:30

9.7 KiB
Raw Blame History

HireAI

HireAI is an AI-powered hiring workspace for preparing and managing technical interviews. Recruiters can sign in with Google, define a role, upload and parse candidate resumes, generate tailored interview questions with Google Gemini, schedule interviews, and look up the pronunciation of technical terms.

The repository contains:

  • Frontend: Vue 3 and Vite single-page application.
  • Backend: FastAPI application with asynchronous MongoDB access.
  • File storage: MongoDB GridFS for original resume files.
  • Authentication: Google OAuth 2.0 with stateless JWT sessions.
  • AI features: Google Gemini for interview-question and pronunciation generation.

Features

  • Google sign-in and protected application routes.
  • Resume upload for PDF and DOC/DOCX files up to 10 MB.
  • Resume text and metadata extraction using PyMuPDF and python-docx.
  • Job/interview requirement management, including mandatory and nice-to-have skills.
  • AI-generated interview questions based on a resume, role, skills, experience, and projects.
  • Interview scheduling with optional meeting links and email notifications.
  • Technical-term pronunciation search, cached in MongoDB, plus a word of the day.
  • Swagger/OpenAPI documentation at /docs and ReDoc at /redoc.

Technology stack

Frontend

  • Vue 3
  • Vue Router 4
  • Axios
  • Vite

Backend

  • Python 3.10+ (Python 3.13 is supported by the current development setup)
  • FastAPI
  • Uvicorn
  • Motor/PyMongo
  • Pydantic Settings
  • PyMuPDF
  • python-docx
  • python-jose
  • fastapi-mail
  • Google GenAI SDK

Services

  • MongoDB (required)
  • Google Cloud OAuth 2.0 credentials (required for sign-in)
  • Google Gemini API key (required for AI generation)
  • SMTP server (required only for interview email delivery)

Repository structure

.
├── backend/
│   ├── app/
│   │   ├── models/          # Pydantic request/response models
│   │   ├── routers/          # Authentication and feature API routes
│   │   └── services/        # Email, Gemini, and resume parsing services
│   ├── main.py              # FastAPI application entry point
│   └── requirements.txt
├── frontend/
│   ├── public/               # Static assets and favicon
│   ├── src/
│   │   ├── api/              # Axios client
│   │   ├── components/       # Shared navigation and footer
│   │   ├── composables/      # Shared auth and toast state
│   │   ├── router/           # Vue Router and auth guard
│   │   └── views/            # Application screens
│   ├── package.json
│   └── vite.config.js
└── README.md

Prerequisites

Install the following before starting:

  1. Python 3.10 or newer.
  2. Node.js 18 or newer and npm.
  3. A running MongoDB instance, either local or MongoDB Atlas.
  4. A Google Cloud OAuth client configured as a Web application.
  5. A Google Gemini API key.
  6. An SMTP account if scheduled interview emails should be sent.

Configuration

Backend environment variables

Create backend/.env with the following values. The backend loads this file through pydantic-settings; do not commit it.

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# JWT
JWT_SECRET=replace-with-a-long-random-secret
JWT_ALGORITHM=HS256
JWT_EXPIRE_HOURS=168

# MongoDB
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=hireai

# Google Gemini
GEMINI_API_KEY=your-gemini-api-key

# Application URLs
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:8000

# SMTP (optional during local development)
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_FROM=your-sender@example.com
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_TLS=true
MAIL_SSL=false

For local Google OAuth development, add this authorized redirect URI to the Google Cloud OAuth client:

http://localhost:8000/api/auth/google/callback

The frontend currently uses http://localhost:8000 as its API origin. If the backend runs elsewhere, update the base URL in frontend/src/api/index.js and the Google login redirect in frontend/src/composables/useAuth.js.

Local development

1. Start MongoDB

Start MongoDB locally or provide a MongoDB Atlas connection string through MONGODB_URI. The backend verifies the connection during application startup.

2. Install and start the backend

From PowerShell:

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

The API is available at http://localhost:8000. Verify it with:

If PowerShell execution policy prevents activation, run the Uvicorn command with the virtual-environment interpreter instead:

.\.venv\Scripts\python.exe -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. Install and start the frontend

In a second terminal:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

For a production-like frontend build:

npm run build
npm run preview

Typical user flow

  1. Open the frontend and sign in with Google.
  2. Create interview requirements for a role.
  3. Upload a candidate resume from the Resume page.
  4. Select the resume and requirement set on the Questions page.
  5. Generate tailored interview questions with Gemini.
  6. Schedule an interview and optionally provide a meeting link.
  7. Use the Pronunciation page to prepare for unfamiliar technical terms.

API overview

All protected endpoints use the JWT created by the Google OAuth callback. The frontend stores the token in localStorage under hireai_token and sends it as a Bearer token through the Axios client.

Area Method Endpoint Authentication
Auth GET /api/auth/google/login Public
Auth GET /api/auth/google/callback OAuth callback
Auth GET /api/auth/me Required
Auth POST /api/auth/logout Public/stateless
Resumes POST /api/resume/upload Required
Resumes GET /api/resume/ Required
Resumes GET /api/resume/{resume_id} Required
Resumes GET /api/resume/{resume_id}/download Required
Resumes DELETE /api/resume/{resume_id} Required
Requirements POST /api/requirements/ Required
Requirements GET /api/requirements/ Required
Requirements GET/PUT/DELETE /api/requirements/{req_id} Required
Questions POST /api/questions/generate Required
Questions GET /api/questions/{resume_id} Required
Schedule POST /api/schedule/ Required
Schedule GET /api/schedule/ Required
Schedule GET /api/schedule/{sched_id} Required
Schedule PUT /api/schedule/{sched_id}/status Required
Schedule DELETE /api/schedule/{sched_id} Required
Pronunciation GET /api/pronunciation/tech-terms Public
Pronunciation GET /api/pronunciation/word-of-the-day Public
Pronunciation GET /api/pronunciation/{word} Public

The interactive OpenAPI documentation at /docs is the authoritative source for request and response schemas.

Data and storage

MongoDB collections are created and used as needed by the application:

  • users — Google profile and login timestamps.
  • resumes — parsed resume metadata and extracted content.
  • requirements — role requirements owned by a user.
  • questions — generated question sets associated with a resume and role.
  • schedules — scheduled interviews owned by a user.
  • pronunciations — cached technical-term pronunciation results.
  • resumes.files and resumes.chunks — GridFS storage for original files.

The application does not include database migrations or seed scripts. Back up MongoDB, including the GridFS collections, before deleting or replacing data.

Development notes

  • Run the backend from the backend directory so main:app and the app package resolve correctly.
  • Keep Google, Gemini, JWT, SMTP, and MongoDB credentials in environment files or a secret manager.
  • The backend allows the configured FRONTEND_URL and http://localhost:5173 through CORS.
  • Uploaded resumes are restricted to PDF/DOC/DOCX content types and 10 MB.
  • The frontend has no automated test script configured in package.json. Use npm run build as the available frontend verification command.
  • The backend currently has no test suite or test command in the repository.

Troubleshooting

MongoDB connection errors

Confirm MongoDB is running and that MONGODB_URI points to the correct instance. The API will not complete startup until its initial MongoDB ping succeeds.

Google OAuth redirect errors

Make sure the authorized redirect URI exactly matches BACKEND_URL/api/auth/google/callback, and that GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, FRONTEND_URL, and BACKEND_URL agree with the URLs used to start both applications.

AI generation failures

Confirm GEMINI_API_KEY is present and available to the backend process. Check the FastAPI terminal output and /docs response body for the returned error.

Interview email failures

Verify the SMTP credentials and sender settings. Scheduling is persisted in MongoDB before the email notification is attempted, so an email configuration problem does not remove the scheduled interview.

License

No license file is currently included in this repository. Add a license before distributing the project publicly.