How m-coder-umer/resume_analyzer works
1. This repository is a resume screening and candidate ranking system built around two entry points: a FastAPI backend for API-driven workflow execution and a Streamlit UI for recruiter-facing interaction. The backend is the system of record; the UI is a consumer of its endpoints.
2. The central orchestration boundary is src/pipeline.py. It coordinates the end-to-end flow across ingestion, extraction, job analysis, matching, ranking, and persistence, rather than letting API handlers talk to each subsystem directly.
3. Resume ingestion starts in src/ingestion/, where PDF resumes are parsed into text. That text becomes the input to extraction. The repository includes sample PDFs and extracted text under data/sample_resumes, which suggests a batch-processing workflow with file-based inputs.
4. Candidate extraction is split into two strategies in src/extraction/: a rule-based extractor for deterministic fields and an LLM-based extractor for richer structured output. The README indicates Groq-hosted Llama is used for the LLM path, with skill verification to reduce hallucinated skills.
5. Job-description analysis lives in src/jobspec/jd_analyzer.py. This subsystem turns a free-form job description into structured job requirements that the matching layer can consume, creating a symmetric representation between “candidate profile” and “job spec.”
6. Matching is intentionally hybrid. src/matching/keyword_matcher.py scores explicit skill overlap, while src/matching/semantic_matcher.py uses embeddings for similarity. src/ranking/scorer.py combines those signals with experience fit into the final score, producing explainable output rather than a black-box rank.
7. Persistence is split by data type. src/storage/db.py wraps SQLite for structured entities like candidates, jobs, batches, and match results, while src/storage/vector_store.py wraps ChromaDB for embedding storage and similarity lookup. The checked-in data/ directory shows both the SQLite database and Chroma persistence files, so these are durable local stores rather than ephemeral caches.
8. The system has an asynchronous batch-processing model. Resume uploads create a batch, then each resume is processed independently with progress tracked by batch ID. The README notes Celery + Redis as the preferred background-task path, with an asyncio fallback, which means processing is decoupled from request/response time.
9. API routing is separated by domain in src/api/: resumes, jobs, matching, and admin. These endpoints expose the pipeline as a set of coarse-grained actions: upload resumes, inspect batch status, analyze a job, trigger matching, and fetch ranked results.
10. Shared contracts and runtime configuration live in src/core/. schemas.py defines the Pydantic data models that stabilize boundaries between API, pipeline, and storage; config.py centralizes environment-driven settings like database URL, embedding model, and scoring weights; exceptions.py provides domain-specific error handling.
11. src/main.py is the FastAPI application bootstrap, while src/ui/app.py is the separate Streamlit front end. This makes the system a two-process architecture: a backend service for computation and persistence, and a client app for visualization and human review.
12. The repository’s tests/ focus on API behavior, which reflects the architecture’s public surface area being the HTTP contract. Overall, the key diagram should show a request-driven API layer, an orchestration/pipeline layer, specialized NLP/matching subsystems, and two storage backends: SQLite for records and ChromaDB for embeddings.
Main entry points: pipeline.py Pipeline · schemas.py Schemas · main.py Main app · app.py Streamlit UI
Components 20
API layer
HTTP entry points for resume, job, matching, and admin actions.
- Main app · Starts the backend service and wires the API application.
src/main.py - Resume API · Endpoints for resume upload and batch progress.
src/api/resumes.py - Job API · Endpoints for job description analysis and job-spec handling.
src/api/jobs.py - Match API · Endpoints that trigger matching and return ranked candidates.
src/api/matching.py - Admin API · Operational endpoints for internal inspection and control.
src/api/admin.py
Orchestration
Central workflow that coordinates ingestion, extraction, analysis, matching, ranking, and persistence.
- Pipeline · Coordinates the end-to-end resume screening workflow.
src/pipeline.py - PDF ingestion · Extracts text from resume PDFs for downstream processing.
src/ingestion/pdf_extractor.py
NLP and matching
Resume and job understanding plus hybrid scoring.
- Rule extractor · Deterministic field extraction from resume text.
src/extraction/rule_base.py - LLM extractor · LLM-backed resume extraction for richer candidate profiles.
src/extraction/llm_extractor.py - JD analyzer · Converts free-form job descriptions into structured requirements.
src/jobspec/jd_analyzer.py - Keyword match · Scores explicit skill and requirement overlap.
src/matching/keyword_matcher.py - Semantic match · Uses embeddings to measure candidate-job similarity.
src/matching/semantic_matcher.py - Rank scorer · Combines matching signals and experience fit into an explainable score.
src/ranking/scorer.py
Storage
Persistent stores for structured records and embeddings.
- SQLite store · Stores candidates, jobs, batches, and match results.
src/storage/db.py - Vector store · Stores embeddings and supports similarity lookup via ChromaDB.
src/storage/vector_store.py
Clients
Human-facing UI and background task runtime.
- Streamlit UI · Recruiter-facing interface for reviewing results and interacting with the backend.
src/ui/app.py - Task workers · Asynchronous batch processing for resume screening.
workers/tasks.py
Other components
- Schemas · Pydantic models that define data boundaries across the system.
src/core/schemas.py - Config · Environment-driven settings for models, database, and scoring.
src/core/config.py - Exceptions · Shared application and domain error types.
src/core/exceptions.py
Connections 30
- Main app → Resume API: serves · Bootstraps the resume workflow endpoints.
- Main app → Job API: serves · Bootstraps the job analysis endpoints.
- Main app → Match API: serves · Bootstraps the matching endpoints.
- Main app → Admin API: serves · Bootstraps the admin endpoints.
- Resume API → Pipeline: starts · Hands uploaded resumes into the orchestration layer.
- Job API → JD analyzer: analyzes · Transforms raw job descriptions into structured specs.
- Match API → Pipeline: triggers · Runs matching and ranking through the pipeline.
- Admin API → SQLite store: reads · Exposes operational data from persistent storage.
- Pipeline → PDF ingestion: ingests · Parses resume files into text.
- Pipeline → Rule extractor: extracts · Uses deterministic extraction for core fields.
- Pipeline → LLM extractor: extracts · Uses LLM extraction for richer structured output.
- Pipeline → JD analyzer: builds spec · Converts job descriptions into matchable requirements.
- Pipeline → Keyword match: scores · Computes explicit skill overlap.
- Pipeline → Semantic match: scores · Computes embedding-based similarity.
- Pipeline → Rank scorer: ranks · Combines signals into the final candidate score.
- Pipeline → SQLite store: persists · Stores batches, candidates, jobs, and match results.
- Pipeline → Vector store: stores embeddings · Writes and queries vector representations.
- Rule extractor → Schemas: emits · Produces structured candidate data models.
- LLM extractor → Schemas: emits · Produces structured candidate data models.
- JD analyzer → Schemas: emits · Produces structured job-spec models.
- Keyword match → Schemas: consumes · Uses candidate and job contracts as input.
- Semantic match → Vector store: queries · Relies on stored embeddings for similarity lookup.
- Rank scorer → Schemas: consumes · Combines structured inputs for explainable ranking.
- Task workers → Pipeline: runs · Executes batch processing outside request time.
- Streamlit UI → Resume API: calls · Uses backend endpoints for uploads and status.
- Streamlit UI → Job API: calls · Uses backend endpoints for job analysis.
- Streamlit UI → Match API: calls · Uses backend endpoints for ranking requests.
- SQLite store → Config: configured by · Database connection and paths come from runtime settings.
- Vector store → Config: configured by · Vector store behavior comes from runtime settings.
- Pipeline → Exceptions: raises · Uses shared domain error handling across stages.