Hire-ai/README.md

# 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

```text
.
├── 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.

```dotenv
# 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:

```text
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`](frontend/src/api/index.js) and the Google login
redirect in [`frontend/src/composables/useAuth.js`](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:

```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:

- Health check: <http://localhost:8000/health>
- Swagger UI: <http://localhost:8000/docs>
- ReDoc: <http://localhost:8000/redoc>

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

```powershell
.\.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:

```powershell
cd frontend
npm install
npm run dev
```

Open <http://localhost:5173>.

For a production-like frontend build:

```powershell
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.