first commit
This commit is contained in:
commit
7a72438fd1
74 changed files with 7548 additions and 0 deletions
298
README.md
Normal file
298
README.md
Normal file
|
|
@ -0,0 +1,298 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue