StaffFlow

An AI candidate-matching PoC for staffing agencies — Supabase + Anthropic, with a validation gate.

A worked solutions-architecture example: customer problem → solution design → working proof-of-value. — Tony Kus

Recruiters at a mid-sized staffing firm ("Nordstaff AB") manually match consultants to open assignments across spreadsheets and email. StaffFlow takes an assignment, returns a ranked shortlist in seconds, and drafts a client-ready justification for each candidate — with a validation gate so the recruiter approves before anything ships. AI proposes, human decides.

It also supports semantic candidate search (RAG): describe who you need in plain language, get candidates retrieved by meaning (pgvector), explained by AI grounded only in the retrieved records. Embeddings use Supabase's built-in gte-small model — no external embeddings key.

Demo

• Live: https://tonyk91.github.io/staffflow/ — click an assignment → "Find matches", or use the semantic search box

Production RAG service (Python · LlamaIndex)

Beyond the live demo, rag-service/ is a Python implementation of the retrieval layer, built the way a production RAG system is built so its quality can be measured rather than assumed:

• chunking · local embeddings · hybrid retrieval (dense vector + BM25 via reciprocal-rank fusion) · cross-encoder reranking · grounded generation with a source trail
• a retrieval-evaluation harness (Hit Rate / MRR / Recall@k) comparing vector vs BM25 vs hybrid vs hybrid+rerank — hybrid+rerank gives the best recall

Full write-up and results: rag-service/README.md.

How it's built

Layer	Tech	Why
Frontend	Standalone HTML/JS (index.html)	Zero-dependency, opens in any browser; talks straight to the backend
Data	Supabase (candidates, assignments)	Clean system of record + easy to extend
AI	Anthropic API (Claude)	Match scoring + justification drafting
Retrieval	pgvector + Supabase gte-small embeddings	Semantic candidate search (RAG), no external embeddings key
Trust	Validation gate	No AI output reaches the user unverified

The backend is intentionally portable — the Supabase edge function and schema work behind any frontend, so the same proof-of-value can be re-skinned for different tools or demos.

See SOLUTION.md for the full solution design, docs/architecture.md for the architecture, and docs/test-result.md for a verified end-to-end run.

Repo map

• rag-service/ — Python · LlamaIndex production RAG: hybrid retrieval + reranking + evaluation harness
• SOLUTION.md — the solutions-architecture write-up (the core artifact)
• index.html — standalone frontend (assignment cards → ranked, validated shortlist)
• docs/architecture.md — architecture diagram + data flow
• docs/test-result.md — verified end-to-end result
• supabase/schema.sql — tables + seed data
• supabase/rag_schema.sql — pgvector + similarity search function (RAG add-on)
• supabase/functions/match-candidates/ — edge function: scoring, drafting, validation gate
• supabase/functions/search-candidates/ — edge function: semantic search (retrieve → ground → gate)
• evals/validation_gate.test.ts — tests proving the AI output is verified, not assumed

Run it

1. Create a Supabase project, run supabase/schema.sql in the SQL editor.
2. (RAG) run supabase/rag_schema.sql to enable pgvector + the similarity search function.
3. Deploy the edge functions: supabase functions deploy match-candidates and supabase functions deploy search-candidates (or paste them via the dashboard editor).
4. Set the secret: supabase secrets set ANTHROPIC_API_KEY=...
5. Put your project URL + anon key at the top of index.html, then open it in a browser. The first semantic search backfills candidate embeddings automatically.

Design highlights

• Validation gate is a first-class step — every cited skill is checked against the candidate's real record; unverifiable claims are stripped and the candidate is flagged needs_review. The model never silently asserts facts.
• Server-side AI — the Anthropic key lives in the edge function, giving one place to add rate limiting, caching, and audit logging.
• Scoping shown on purpose — auth, multi-tenant isolation, and ATS integration are listed under "Path to enterprise" in SOLUTION.md rather than half-built.