Job Recommendation System 🚀

An AI-driven job recommendation platform.
Users log in, upload a resume, and an LLM generates 7–8 tailored questions. Resume data + answers are scored:

Score < 60 → show popup warning, user may retry.
Score ≥ 60 → system fetches jobs (e.g., from LinkedIn) and recommends them via LangChain reranking.

⚡ Quick Start in 1 Minute (with Docker)

git clone https://github.com/your-org/job-recommendation-system.git
cd job-recommendation-system
cp .env.example .env   # edit values
docker compose up -d   # build & start

Access Points:

🌐 API → http://localhost:8000/health
🗄️ Database → auto-created (schema + migrations from data/sql/)

🛠️ Development Workflow

Running Development Scripts

We provide automated development scripts that handle Docker services, code quality checks, and testing:

For Linux/macOS:

# Using npm script (recommended)
npm run devrun

# Or directly
./devrun.sh

For Windows:

devrun.cmd

What the Dev Scripts Do

The devrun scripts automate your entire development workflow:

🐳 Start Docker Services - Brings up all containers (backend, frontend, databases, etc.)
🔍 Run Quality Checks:
- Python (Backend):
  - ruff - Fast Python linter
  - black --check - Code formatting verification
  - pytest - Run all tests
- Node.js (Frontend):
  - eslint - JavaScript/TypeScript linting
  - prettier --check - Code formatting verification
  - next lint - Next.js specific linting
  - jest - Run all frontend tests
📊 Generate Summary - Shows which checks passed/failed
🛑 Clean Shutdown - Automatically stops Docker services when done

Exit Codes

0 - All checks passed ✅
1 - One or more checks failed ❌

Prerequisites

Before running the dev scripts, ensure you have:

Docker & Docker Compose installed
Node.js & npm installed (for npm script)
Executable permissions (Linux/macOS):
```
chmod +x devrun.sh
```

Development Best Practices

Run before committing:

npm run devrun  # Ensures code quality before pushing

Fix issues automatically (where possible):

# Python formatting
docker compose exec backend black .

# Node formatting
docker compose exec frontend npx prettier --write .

Run specific checks:

# Just Python tests
docker compose exec backend pytest

# Just frontend linting
docker compose exec frontend npx eslint .

Troubleshooting Dev Scripts

Script exits immediately:

Check Docker is running: docker --version
Verify Docker Compose: docker compose version

Permission denied (Linux/macOS):

chmod +x devrun.sh

Checks failing:

Review the specific error messages in the output
Run formatters to auto-fix: black . or prettier --write .
Check test logs for failing tests

Services won't start:

# Clean restart
docker compose down -v
docker compose up -d

🌱 Environment Modes

The entire stack now reads a single SERVER_ENV flag (local, staging, production) so you can branch logic with simple helpers:

Backend (common/server_environment.py) exposes get_server_environment() which returns booleans like is_local, is_staging, is_prod. Both FastAPI apps (Job API + Resume Reader) import this helper so any service can branch on the same flags.
Frontend (job-recommendation-system/front-end/lib/server/environment.ts) mirrors the same contract so API routes and pages can ask for isLocal, isStaging, etc.
Any other frontend (e.g., a future Resume Reader UI) can import from frontend-common/environment directly:

import { resolveServerEnvironment } from "../../frontend-common/environment";

const serverEnv = resolveServerEnvironment();
if (serverEnv.isLocal) {
  // local-only logic
}

Supporting variables (all live in .env / deployment secrets):

Variable	Purpose	Example
`SERVER_ENV`	Active environment slug	`local`, `staging`, `production`
`API_BASE_URL`	Where the frontend talks to the backend	`http://localhost:8000`
`FRONTEND_ORIGIN`	Primary UI origin allowed by CORS	`http://localhost:3000`
`CORS_EXTRA_ORIGINS`	Optional comma list of additional origins	`https://staging.example.com`

When SERVER_ENV=local, sensible defaults are applied (localhost ports). For staging/prod just set the URLs explicitly—both backend and frontend modules will stay in sync.

📂 Repository Structure

.
├── job-recommendation-framework/      # Framework: AI & LangChain
│   └── framework/
│
├── job-recommendation-system/         # Main system
│   ├── core/                          # business logic & entities
│   ├── web/                           # FastAPI API layer
│   ├── frontend/                      # React/NxT.js UI
│   └── data/sql/                      # DB migrations (DDL/DML)
│       ├── Major_01_00_00/            # schema
│       └── Major_02_00_00/            # future DDL
│
├── docker/                            # Docker configs
│   ├── Dockerfile.api
│   ├── entrypoint.api.sh
│   └── db-seed.sh
│
├── docker-compose.yml
├── .env.example
├── .dockerignore
├── Makefile                           # dev shortcuts
└── README.md

⚡ Quick Command Reference

Task	Command	Description
Run all checks	`npm run devrun`	Start services, run all quality checks, generate report
Start services	`docker compose up -d`	Start all containers in background
Stop services	`docker compose down`	Stop all containers
View logs	`docker compose logs -f`	Follow logs from all services
Service logs	`docker compose logs -f backend`	Follow logs from specific service
Format Python	`docker compose exec backend black .`	Auto-format Python code
Format Node	`docker compose exec frontend npx prettier --write .`	Auto-format frontend code
Python tests	`docker compose exec backend pytest`	Run backend tests
Frontend tests	`docker compose exec frontend npx jest`	Run frontend tests
Rebuild	`docker compose build --no-cache`	Clean rebuild all containers
Database reset	`docker compose down -v && docker compose up -d`	Reset database and restart

🧭 High-Level Flow

Frontend (React/NxT.js) → login, resume upload, Q&A, jobs view
API (FastAPI) → /resume, /qa/*, /score, /jobs/recommend
Core → parsing, scoring, job recommendation
Framework → LangChain parsing assist, QGen, scoring, reranking
Job Source → LinkedIn scraper / adapter

Final Score = 0.6 × ResumeScore + 0.4 × QAScore

< 60 → retry
≥ 60 → job recommendations

🔌 Module Responsibilities

🧠 job-recommendation-framework

LLM-based resume parsing, question generation, answer scoring, job reranking.
Independent package — plug & play with system.