🛡️ JobShield — Fake Job Posting Detector

JobShield is a full-stack machine-learning-powered web application that detects fraudulent job postings. It combines a React + Vite frontend with a FastAPI backend that serves an XGBoost classifier trained on NLP-preprocessed job listing data.

---

📁 Project Structure

JobSheild/
├── Backend/
│   ├── app.py              # FastAPI server entry point
│   ├── data/               # Raw and cleaned datasets
│   ├── models/             # Saved trained model & vectorizer
│   ├── reports/            # Evaluation metrics & feature importances
│   └── src/
│       ├── config.py       # Centralized path & config constants
│       ├── preprocess.py   # Text cleaning, lemmatization, TF-IDF vectorization
│       ├── model.py        # XGBoost model definition
│       ├── train.py        # Model training script
│       └── predict.py      # Inference / prediction logic
├── Frontend/
│   ├── index.html
│   ├── vite.config.js
│   ├── package.json
│   └── src/
│       ├── App.jsx
│       ├── main.jsx
│       └── components/     # React UI components
├── requirement.txt         # Python dependencies
└── README.md

---

⚙️ Prerequisites

Make sure the following are installed on your system before proceeding:

Tool	Version	Download
Python	3.11 (recommended)	python.org
Node.js	18+	nodejs.org
Conda (optional)	Latest	anaconda.com
Git	Any	git-scm.com

---

🐍 Setting Up a Python Virtual Environment

Recommendation: Always use a virtual environment to keep project dependencies isolated and avoid conflicts with other Python projects on your system.

✅ Option 1 — Conda (Recommended)

Conda manages both the Python version and dependencies, making it the most reliable option for this project.

1. Create a new Conda environment with Python 3.11:

conda create -n jobshield python=3.11

2. Activate the environment:

conda activate jobshield

3. Verify the Python version:

python --version
# Expected: Python 3.11.x

4. When you are done working, deactivate the environment:

conda deactivate

---

Option 2 — Python venv (Standard Library)

If you do not have Conda installed, use Python's built-in venv module.

1. Navigate to the project root:

cd path/to/JobSheild

2. Create the virtual environment:

python -m venv venv

3. Activate it:

• Windows (PowerShell):

  .\venv\Scripts\Activate.ps1

• Windows (Command Prompt):

  venv\Scripts\activate.bat

• macOS / Linux:

  source venv/bin/activate

---

🚀 Running the Project

Step 1 — Clone the Repository

git clone https://github.com/your-username/JobSheild.git
cd JobSheild

---

Step 2 — Backend Setup (FastAPI + ML Model)

1. Activate your virtual environment (Conda or venv — see above).

2. Install all Python dependencies:

pip install -r requirement.txt

3. Download the spaCy English language model (required for NLP preprocessing):

python -m spacy download en_core_web_sm

4. Train the machine learning model (run only once — skipped automatically on subsequent runs if cached files exist):

cd Backend/src
python train.py

This will preprocess the dataset, train the XGBoost classifier, and save the model and vectorizer to Backend/models/.

5. Start the FastAPI server:

cd Backend
python app.py

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

You can verify it is running by visiting: http://localhost:8000 — it should return:

{ "status": "online", "message": "JobShield API is running" }

The interactive API docs are available at: http://localhost:8000/docs

---

Step 3 — Frontend Setup (React + Vite)

Open a new terminal (keep the backend running).

1. Navigate to the Frontend directory:

cd Frontend

2. Install Node.js dependencies:

npm install

3. Start the development server:

npm run dev

The frontend will be available at: http://localhost:5173

---

🔄 Running the Full Stack

Once both servers are running simultaneously, the application is fully functional:

Service	URL
React Frontend	http://localhost:5173
FastAPI Backend	http://localhost:8000
API Interactive Docs	http://localhost:8000/docs

---

📦 Python Dependencies

Listed in requirement.txt. Key packages include:

Package	Purpose
fastapi	REST API framework
uvicorn	ASGI server for FastAPI
scikit-learn	TF-IDF vectorizer, model evaluation
xgboost	Gradient boosted classifier
nltk	Stopwords corpus
spacy	Tokenization & lemmatization (en_core_web_sm)
pandas	Dataset loading and manipulation
numpy	Numerical operations
joblib	Model and vectorizer serialization
matplotlib	(Optional) Visualization

---

🖥️ Frontend Tech Stack

Package	Purpose
react + react-dom	UI library
vite	Fast dev server & bundler
react-router-dom	Client-side routing
framer-motion / motion	Animations
lucide-react + react-icons	Icon libraries
tailwindcss	Utility-first CSS

---

⚠️ Common Issues & Fixes

spacy model not found:

python -m spacy download en_core_web_sm

PowerShell script execution policy error (Windows):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then re-activate your venv.

ModuleNotFoundError for backend modules:
Always run app.py from inside the Backend/ directory:

cd Backend
python app.py

CORS errors in the browser:
Ensure the FastAPI server is running on port 8000 and the frontend is running on port 5173. These are the pre-configured allowed origins.