Recruitment Assistant

AI-powered multi-agent recruitment workflow automation built with CrewAI and the AAMAD framework.

Current Status: Deliver Phase Complete

| Phase | Status | Artifacts | |---|---|---| | Phase 1 — Define | Complete | MRD · PRD | | Phase 2 — Build | Complete | SAD · Backend plan · Frontend plan · Integration plan · QA plan | | Phase 3 — Deliver | Complete | Deployment plan · Monitoring plan · Runbook · Execution results |

Quick Start

The full operations guide is in the Runbook. The short version:

# 1. Clone and configure
git clone <repo-url>
cd recruitment-assistant
cp .env.example .env
# Set OPENAI_API_KEY in .env

# 2. Start
docker compose up --build

# 3. Open
open http://localhost:3000

First run: ~90 seconds to build. Subsequent starts: ~15 seconds.

| URL | Purpose | |---|---| | http://localhost:3000 | Recruiter UI | | http://localhost:8000/docs | API docs (Swagger) | | http://localhost:8000/health | Health check |

See the Runbook for configuration, troubleshooting, monitoring, and the full recruiter workflow.

What It Does

Recruitment Assistant cuts time-to-shortlist from 8–12 hours to under 20 minutes. A recruiter uploads a job description and up to 200 resumes. Four AI agents run the pipeline:

| Step | Agent | Output | |---|---|---| | 1 | Job Description Analyst | Structured requirements (skills, experience, responsibilities) | | 2 | Resume Screener ×N (parallel) | Per-criterion scores (0–10) with rationale for each candidate | | 3 | Candidate Ranker | Ranked shortlist with overall scores and ranking rationale | | 4 | Outreach Drafter ×M | Personalized outreach email draft per approved candidate |

The recruiter approves two human gates — shortlist and outreach review — before anything is sent.

Estimated annual savings for a 500-person company hiring 50 roles/year: $75,000–$150,000.

Architecture

Browser (localhost:3000)
    │  HTTP + WebSocket
    ▼
Next.js 15 frontend
    │  REST API
    ▼
FastAPI backend (localhost:8000)
    │  asyncio.to_thread
    ▼
CrewAI crew (sequential + parallel batch)
    └── OpenAI API (GPT-4o / GPT-4o-mini)

Storage: SQLite · Local filesystem (MVP)

Stack

| Layer | Technology | |---|---| | Agent orchestration | CrewAI (sequential process + kickoff_for_each) | | Backend API | FastAPI + uvicorn (Python 3.11) | | Frontend | Next.js 15, React 19, Tailwind CSS, Zustand | | Database | SQLite (MVP) → PostgreSQL (Phase 2) | | File storage | Local filesystem (MVP) → S3-compatible (Phase 2) | | LLM provider | OpenAI (GPT-4o / GPT-4o-mini) | | Containerisation | Docker / Docker Compose | | Tracing | CrewAI AMP (crewai login + CREWAI_TRACING_ENABLED=true) |

Project Structure

recruitment-assistant/
├── backend/
│   ├── config/
│   │   ├── agents.yaml          # CrewAI agent definitions (role, goal, backstory, LLM)
│   │   └── tasks.yaml           # CrewAI task definitions
│   ├── crew/
│   │   ├── recruitment_crew.py  # Crew builders (JD, Screening, Ranking, Outreach)
│   │   ├── runner.py            # Async run orchestration + human gates
│   │   └── callbacks.py        # step_callback → WebSocket events
│   ├── middleware/
│   │   ├── logging_config.py    # Structured logging setup (dev + JSON production)
│   │   ├── request_logging.py   # HTTP access log middleware
│   │   └── sanitizer.py         # PII redaction for blind screening
│   ├── models/
│   │   ├── db.py                # SQLite schema + init
│   │   └── schemas.py           # Pydantic models (JobRequirements, CandidateScore, etc.)
│   ├── routers/
│   │   ├── upload.py            # POST /api/upload
│   │   ├── runs.py              # POST /api/run-crew, GET /api/results, retry
│   │   ├── approve.py           # POST /api/approve (human gates)
│   │   └── export.py            # GET /api/results/{id}/export (CSV)
│   ├── services/
│   │   ├── run_store.py         # DB access layer
│   │   ├── file_parser.py       # PDF/DOCX text extraction
│   │   └── ws_manager.py        # WebSocket connection manager
│   ├── main.py                  # FastAPI app entry point
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── app/
│   │   ├── run/new/page.tsx     # New screening run wizard
│   │   └── run/[runId]/page.tsx # Live run: progress, shortlist, outreach
│   ├── components/
│   │   ├── upload/              # JD and resume upload zones
│   │   ├── progress/            # Real-time agent status (WebSocket)
│   │   ├── shortlist/           # Ranked candidate table + approval gate
│   │   └── outreach/            # Outreach email editor + review gate
│   ├── lib/
│   │   ├── api.ts               # Typed fetch wrappers
│   │   └── schemas.ts           # Zod schemas mirroring Pydantic models
│   ├── store/runStore.ts         # Zustand run state
│   ├── Dockerfile
│   └── package.json
├── project-context/
│   ├── 1.define/                # MRD, PRD
│   ├── 2.build/                 # SAD, backend/frontend/integration/QA plans
│   └── 3.deliver/               # Deployment plan, monitoring plan, runbook, execution results
├── scripts/
│   └── start.sh                 # Local dev helper (no Docker)
├── .env.example                 # Environment variable reference
├── docker-compose.yml
├── LESSONS.md                   # Project retrospective
└── README.md

Key Artifacts

| Artifact | Description | |---|---| | PRD | Product requirements, user personas, success metrics | | SAD | Solution architecture, agent specs, API design | | Deployment plan | Docker Compose setup, rollback procedures | | Monitoring plan | Log levels, formats, CrewAI AMP tracing setup | | Runbook | Full operations guide — install, run, troubleshoot | | Execution results | Test run record | | Lessons learned | Project retrospective across all three phases |

Lessons Learned

A full retrospective is in LESSONS.md. Key takeaways:

What worked well

• YAML-driven agent config made prompts and LLM settings editable without touching Python
• Pydantic output schemas caught LLM hallucinations at the crew boundary, not silently downstream
• Define-first (MRD → PRD → SAD) gave the build phase clear acceptance criteria and fewer scope gaps
• Docker Compose from day one eliminated environment inconsistencies

What was harder than expected

• step_callback in CrewAI is synchronous — bridging it to the async FastAPI WebSocket required run_coroutine_threadsafe
• NEXT_PUBLIC_* vars are baked into the Next.js bundle at build time, not runtime — easy to miss
• Handoff gaps between agents during the Build phase; frontend and backend assumptions didn't always align

What we'd do differently

• Review architecture plans more thoroughly before agents start coding
• Pin exact dependency versions (crewai==x.y.z) for reproducibility
• Run docker compose build in CI on every PR to catch container issues early
• Add a .dockerignore from the start to keep build contexts fast

License

Apache License 2.0. See LICENSE for details.