Hey everyone, Alex here. Welcome back to Coding with Alex at sysseder.com.
If you’ve been on the job market recently—or even if you’ve just left your LinkedIn "Open to Work" badge on by accident—you know that the current state of tech recruiting is, frankly, a dumpster fire. A headline caught my eye on Hacker News this morning that really hit home: "Please don't spam people looking for employment. It's just cruel."
It’s a sentiment we can all get behind. Job seekers are being bombarded with automated, low-effort outreach for roles they aren't qualified for, or worse, roles that are completely beneath their experience level. We’ve all received those emails: "Hey [First_Name], I saw your impressive background in Kubernetes and think you'd be a great fit for our junior front-end React internship!"
As software engineers, systems architects, and DevOps practitioners, our natural instinct when we see a broken, manual, or poorly automated process is to fix it with better engineering. If recruiting is going to be automated (and let’s face it, in 2024, scale demands some level of automation), we need to build systems that respect human time, leverage precise data parsing, and actually understand developer metadata.
Today, we’re going to look at this from a system design perspective. We’ll design and write the core components of a modern, respectful, developer-first sourcing pipeline. We will build an intelligent backend service that parses candidate profiles, evaluates their GitHub metadata, matches them against realistic job requirements using semantic analysis, and ensures we never spam a candidate with irrelevant noise.
The Anatomy of Bad Recruiting Automation
Before we write any code, we need to understand why current recruiter bots are so bad. Most legacy applicant tracking systems (ATS) and sourcing bots rely on simple keyword matching.
If your resume contains the word "Java", a legacy boolean search throws you into the "Java Developer" bucket. It doesn't matter if you wrote three lines of Java in college eight years ago and have spent the last six years writing Rust and Go infrastructure. To a dumb regex parser, Java == Java.
To fix this, our engineering-driven recruitment pipeline needs to do three things:
- Extract Semantic Meaning: Go beyond keyword matching using vector embeddings to understand the context of a developer’s experience.
- Analyze Public Activity: Query APIs (like GitHub) to verify actual technical affinity, rather than relying solely on self-reported resume buzzwords.
- Implement Rate-Limiting and Exhaustive Guardrails: Ensure that a candidate is never messaged twice for the same role, or messaged at all if they have explicitly opted out or don't meet a strict threshold.
System Architecture: The Respectful Sourcing Pipeline
Here is a high-level overview of how we can architect a respectful sourcing engine:
+------------------+ +-------------------+ +---------------------+
| Resume / Profile| ---> | Semantic Parser | ---> | Embeddings Engine |
| Ingestion API | | (Python/spaCy) | | (Sentence-Trans.) |
+------------------+ +-------------------+ +---------------------+
|
v
+------------------+ +-------------------+ +---------------------+
| Candidate DB | <--- | Guardrail Engine | <--- | Vector Matcher |
| (PostgreSQL/pgV) | | (Opt-out/Limits) | | (Cosine Similarity) |
+------------------+ +-------------------+ +---------------------+
Let's dive into the code. We’ll build a Python-based microservice that leverages sentence embeddings for semantic matching and queries the GitHub API to validate a candidate's actual tech stack before any outreach is even considered.
Step 1: Parsing Resumes with Semantic Depth
Instead of relying on regex, we'll use a pre-trained NLP model to generate vector embeddings of our job descriptions and candidate profiles. This allows our system to understand that a developer who writes "EKS, ECS, Terraform, and Python" is highly relevant to a "Platform Engineer" role, even if their resume doesn't explicitly contain the phrase "DevOps".
First, let's set up our Python environment and write the semantic matching engine using sentence-transformers.
# Install dependencies
# pip install sentence-transformers numpy psycopg2-binary requests
from sentence_transformers import SentenceTransformer
import numpy as np
# Load a lightweight, highly accurate semantic model
model = SentenceTransformer('all-MiniLM-L6-v2')
def calculate_similarity(job_description: str, candidate_profile: str) -> float:
"""
Calculate the cosine similarity between a job description and a candidate's profile.
This helps us move away from dumb keyword matching.
"""
embeddings = model.encode([job_description, candidate_profile])
# Calculate cosine similarity
vec_a = embeddings[0]
vec_b = embeddings[1]
similarity = np.dot(vec_a, vec_b) / (np.linalg.norm(vec_a) * np.linalg.norm(vec_b))
return float(similarity)
# Quick Test
job_desc = "Looking for a Cloud Infrastructure Engineer experienced with AWS, Kubernetes, and Terraform."
candidate_1 = "Platform engineer specializing in container orchestration, cloud-native deployments, and IaC."
candidate_2 = "Front-end developer focused on React, Vue, UI/UX design, and CSS frameworks."
print(f"Candidate 1 Match: {calculate_similarity(job_desc, candidate_1):.4f}")
print(f"Candidate 2 Match: {calculate_similarity(job_desc, candidate_2):.4f}")
If you run this code, you'll see that Candidate 1 scores highly (likely above 0.70) because "container orchestration" and "IaC" are semantically close to "Kubernetes" and "Terraform". Candidate 2 will score significantly lower. This prevents our system from spamming front-end devs with infrastructure roles.
Step 2: Verifying Expertise via GitHub Metadata
Recruiters often spam developers based on a single keyword found in a repository they starred five years ago. Let's build a verification step that queries the GitHub API to analyze a candidate’s public repositories. We want to verify their active languages, ensuring they actually write the code we are looking for.
import requests
from typing import Dict, List
def verify_github_affinity(github_username: str, target_languages: List[str]) -> bool:
"""
Queries GitHub's public API to verify if the candidate has actual repository
activity in the languages required for the role.
"""
url = f"https://api.github.com/users/{github_username}/repos?per_page=100"
try:
response = requests.get(url, timeout=10)
if response.status_code != 200:
return False
repos = response.json()
language_counts = {}
for repo in repos:
lang = repo.get("language")
if lang:
language_counts[lang.lower()] = language_counts.get(lang.lower(), 0) + 1
# Check if the candidate has at least one repo in our target languages
for target in target_languages:
if language_counts.get(target.lower(), 0) > 0:
print(f"[VERIFIED] Candidate {github_username} has active repos in: {target}")
return True
return False
except Exception as e:
print(f"Error connecting to GitHub API: {e}")
return False
By coupling semantic resume analysis with actual, real-time code verification, we filter out candidates who might have listed a language on their resume but haven't touched it in years.
Step 3: Implementing Strict Guardrails and Opt-Outs
This is where most automation engines fail. They don't maintain state. If a recruiter runs three different campaigns, a candidate might get three identical emails in a single week. To prevent this, we need a robust database schema that tracks candidate interactions, respects explicit opt-outs, and enforces strict rate-limiting.
Here is a SQL schema built for PostgreSQL that implements these exact guardrails:
CREATE TABLE candidates (
id SERIAL PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
first_name VARCHAR(100),
last_name VARCHAR(100),
github_handle VARCHAR(100),
is_opted_out BOOLEAN DEFAULT FALSE NOT NULL,
last_contacted_at TIMESTAMP WITH TIME ZONE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE outreach_logs (
id SERIAL PRIMARY KEY,
candidate_id INTEGER REFERENCES candidates(id),
job_id VARCHAR(100) NOT NULL,
sent_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
status VARCHAR(50) NOT NULL -- 'SENT', 'FAILED', 'BOUNCED'
);
Now, let’s write the Python logic that enforces these guardrails before any message is queued. This is the "Don't Be Cruel" layer of our system.
import datetime
def should_contact_candidate(conn, candidate_id: int, job_id: str) -> bool:
"""
Enforces strict guardrails to prevent spam:
1. Checks if candidate has opted out.
2. Checks if candidate has been contacted in the last 30 days.
3. Checks if candidate has already been contacted for this specific job.
"""
cursor = conn.cursor()
# 1. Check opt-out status and last contacted date
cursor.execute("""
SELECT is_opted_out, last_contacted_at
FROM candidates
WHERE id = %s
""", (candidate_id,))
candidate = cursor.fetchone()
if not candidate:
return False
is_opted_out, last_contacted_at = candidate
if is_opted_out:
print(f"Candidate {candidate_id} has opted out. Skipping.")
return False
if last_contacted_at:
thirty_days_ago = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=30)
if last_contacted_at > thirty_days_ago:
print(f"Candidate {candidate_id} was contacted recently. Cool-down active. Skipping.")
return False
# 2. Check if already messaged for this specific role
cursor.execute("""
SELECT COUNT(*)
FROM outreach_logs
WHERE candidate_id = %s AND job_id = %s
""", (candidate_id, job_id))
already_contacted_for_job = cursor.fetchone()[0] > 0
if already_contacted_for_job:
print(f"Candidate {candidate_id} was already evaluated/contacted for Job {job_id}. Skipping.")
return False
return True
We Owe It to the Community to Build Better Systems
The developer community thrives on open source, mutual respect, and high-signal communication. When companies use low-effort, spam-heavy automation tools to source talent, they alienate the very engineers they are trying to hire.
By replacing dumb regex engines with semantic parsers, validating technical affinity with active GitHub metrics, and enforcing strict relational guardrails at the database level, we can build recruiting automation that actually works—and respects human dignity in the process.
If you are a lead engineer or an engineering manager involved in hiring at your current company, I challenge you to look at your HR team’s tooling. Ask them what platforms they use. Suggest that your engineering team help them build better integration APIs that respect developer boundaries.
What are your thoughts? What’s the worst, most inaccurate recruiter spam email you’ve ever received? Let’s talk about it in the comments below!
Until next time, keep your code clean, your databases indexed, and your outreach respectful.
— Alex