Prince-Mlingwa/icris-recruitment

ICRIS — Intelligent Centralized Recruitment Information System

Live demo (Hugging Face Space): after deploy, open the Space URL and sign in.

Production-style academic final-year project built with Python, Django, MySQL (or SQLite), HTML, CSS, and JavaScript.

Demo logins (password for all: Demo@12345)

Role	Username
Admin	admin
HR Officer	hr.officer
Hiring Manager	hiring.manager
Applicant	applicant1

Purpose

Automate candidate profile evaluation, reduce manual screening load, and improve HR decision-making with transparency and explainability, while enforcing a strict human-in-the-loop principle:

AI analyzes, scores, explains, and recommends — authorized humans review and approve before the system executes important decisions.

Five project objectives

1. NLP candidate analysis — detect skills, qualifications, experience; normalize; match requirements with evidence
2. Vacancy-specific screening, matching, scoring, ranking, recommendations (no universal employability score)
3. CV parsing — PDF/DOCX/text → structured data; original file preserved
4. Full vacancy management — create/edit/publish/close/archive with weights, thresholds, skills, screening questions
5. Explainable recommendations — component breakdown, matched/missing requirements, human decisions & audit trail

Roles (RBAC)

Role	Login (demo)	Focus
System Administrator	admin	Users, scoring config, skills, templates, audit
HR Officer	hr.officer	Vacancies, workspace, shortlist/rejection, interviews, notifications
Hiring Manager	hiring.manager	Assigned vacancies, AI explanations, feedback
Applicant	applicant1 … applicant6	Profile, apply, journey tracker

Password for all demo accounts: Demo@12345

Pipeline (enforced)

APPLIED → SCORED → PENDING REVIEW
  → SHORTLISTED (DRAFT) or REJECTED (DRAFT)
  → SHORTLIST APPROVED or REJECTION CONFIRMED
  → INTERVIEW SCHEDULED → NOTIFICATION QUEUED → NOTIFIED

Draft shortlists/rejections never send messages automatically. Notifications follow:

Decision → Human approval → Queue → Process → Delivery → Audit

Quick start

cd tawanda
python -m venv .venv
# Windows:
.venv\Scripts\activate
pip install -r requirements.txt

# Default: SQLite (demo). For MySQL set ICRIS_USE_MYSQL=1 and MySQL env vars.
python manage.py migrate
python manage.py seed_demo
python manage.py runserver

Open http://127.0.0.1:8000/ and sign in as hr.officer.

MySQL (optional)

# Create database icris_db, then:
set ICRIS_USE_MYSQL=1
set MYSQL_DATABASE=icris_db
set MYSQL_USER=root
set MYSQL_PASSWORD=yourpassword
set MYSQL_HOST=127.0.0.1
python manage.py migrate
python manage.py seed_demo

Demonstration journey (examiner)

1. Objective 4 — HR → Vacancy Management → open/create/publish vacancy with weights & skills
2. Objective 3 — HR dashboard → Objective 3 “View/Demonstrate” → Original CV vs structured extraction
3. Objective 1 — NLP Analysis → Detected → Normalized → Matched → Unmatched
4. Objective 2 — Ranking for a vacancy → scores, component breakdown, filters
5. Objective 5 — Evaluation detail → overall + components + evidence + decision timeline
6. Operations — Shortlist draft → Approve → Interview batch → Notification queue → Process
7. Rejection — Rejection queue → Confirm / Rescue with reason → queue
8. Switch roles: Admin config · HM feedback · Applicant journey (no confidential scores)

Project layout

icris/           Project settings & URLs
accounts/        Users, RBAC, registration
core/            Org, departments, skills, scoring config
vacancies/       Vacancy CRUD, progress tracker
applications/    Apply, CV storage, parser
evaluation/      NLP engine, weighted scoring, explainability
workflow/        Shortlist, rejection, interview batches
notifications/   Controlled queue (email primary; SMS future)
audit/           AuditLog + decision timelines
dashboards/      Role-specific workflow dashboards
templates/       Enterprise HR UI
static/          CSS (status colour scheme) & JS

Status colour scheme

Colour	Typical use
Blue	Applied / primary actions
Purple	Scored / AI / interview
Yellow-amber	Pending review
Orange	Shortlist draft / attention
Green	Approved / success
Red	Rejection draft / danger
Dark	Notified / admin chrome

Security notes

• Django auth + password hashing, CSRF, session cookies
• Server-side RBAC and object-level checks (not UI-only)
• CV upload extension/size validation
• ORM queries; no blind auto-send of notifications

Tests / verification

After seeding, confirm varied scores for Django vacancy (excellent vs sales CV), then walk each role login and objective link on the HR dashboard.