README.md

metadata

title: Matching Tool
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

Staffinc Client-Fit Matching & Briefing Tool MVP

This is a full-stack monorepo MVP built to optimize Staffinc's recruitment funnel and B2B client conversion rate.

📌 Problem Context

Staffinc candidates pass internal recruiter screenings but historically face a low client-stage interview acceptance rate of ~25% (1 out of 4). Rejection reasons are typically subjective (e.g., "didn't show up well," "communication vibe mismatch").

This B2B tool:

1. Profiles Clients by Vibe: Standardizes expectations into "Consulting/Corporate" or "Startup/Scrappy" archetypes with minimum competency thresholds (using the Behavioral Anchored Rating Scale, BARS).
2. Standardizes Vetting: Recruiters score candidates (1-5) against these specific client thresholds with live behavioral guidance to remove subjectivity.
3. Automates Coaching Briefs: Instantly generates a printable candidate prep guide mapping gaps, practice questions, and tailored coaching tips.
4. Logs Outcomes: Closes the feedback loop by recording final decisions and updating live conversion analytics.

---

🛠️ Tech Stack

• Backend: FastAPI (Python 3.11) + SQLAlchemy + SQLite
• Frontend: React + Vite + Vanilla CSS
• Data Generation: Faker (for mock analytics & sandbox seeding)

---

📂 Project Structure

staffinc/
├── backend/
│   ├── app/
│   │   ├── database.py       # SQLite connection and session local
│   │   ├── models.py         # SQLAlchemy ORM models (Client, Candidate, Score, Feedback)
│   │   ├── schemas.py        # Pydantic v2 validation schemas
│   │   ├── crud.py           # Database CRUD & mismatch checking
│   │   ├── seed.py           # Static BARS questions and default anchors
│   │   ├── seed_dummy.py     # Script to generate realistic mock data
│   │   ├── brief_generator.py# Gap analysis and strategy brief builder
│   │   └── main.py           # REST endpoints and static file mount
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/       # Shared UI (Navbar, ScoreSlider, MismatchAlert)
│   │   ├── pages/            # Page templates (ClientSetup, CandidateScoring, BriefPreview, FeedbackForm)
│   │   ├── App.jsx           # Client router
│   │   └── main.jsx          # React entry point
│   ├── package.json
│   └── vite.config.js
└── README.md

---

🚀 Getting Started

1. Environment Setup

Make sure you have Anaconda or Miniconda installed, then create and activate the environment:

# Create the conda environment
conda create -n daftar-kerja python=3.11 -y

# Activate the environment
conda activate daftar-kerja

2. Backend Installation & Seeding

# Navigate to backend
cd backend

# Install dependencies
pip install -r requirements.txt
pip install faker

# Seed the database with realistic dummy data
python -m app.seed_dummy

3. Frontend Installation

# Navigate to frontend (from project root)
cd ../frontend

# Install node dependencies
npm install

---

💻 Running the Application

Option A: Unified Service (Production Build)

Build the React frontend assets, and let FastAPI serve both the API and the static site:

# 1. Build frontend (generates frontend/dist/)
cd frontend
npm run build

# 2. Run backend (serves API and front-end on http://127.0.0.1:8000)
cd ../backend
uvicorn app.main:app --host 127.0.0.1 --port 8000

Option B: Split Development Server

Run Vite's dev server with Hot Module Replacement alongside the FastAPI dev server:

# Run backend (dev reload)
cd backend
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

# Run frontend dev server (in a separate terminal)
cd frontend
npm run dev

(Vite is configured to automatically proxy /api calls to the backend running at port 8000).

---

🧪 E2E Verification Script

To test the full B2B matching and briefing cycle programmatically, run:

python -m urllib.request -e http://127.0.0.1:8000/api/stats

Or use our custom verification test script:

# Verify client creation, vetting, brief generation, and dashboard logging
python -m app.verify_e2e