How lawk-0/adaptive-resume-screener works
Adaptive Resume Screener is organized as a small but complete system with four major boundaries: a browser-based UI, a FastAPI application layer, a local persistence layer backed by SQLite, and an offline ML pipeline that produces the model artifact the API uses at inference time.
At a high level, the online path is:
1. A user uploads a resume and provides a job description in the frontend.
2. The backend parses the resume text, analyzes the match against the job description, and runs a PyTorch model over engineered features.
3. The system returns an explainable screening result with scores and a shortlist/reject recommendation.
4. The prediction is stored in SQLite.
5. The user can submit feedback later, which is written back to the same database for future retraining.
Main subsystems
1. Frontend presentation layer
• The primary browser UI lives in frontend/index.html, frontend/app.js, and frontend/styles.css.
• A second static asset set exists in public/, which is intended for deployment environments like Vercel.
• This layer is intentionally lightweight: it collects user input, displays analysis results, and sends feedback to the backend.
• It does not contain business logic or ML logic; it is purely the interaction surface.
2. FastAPI backend application
• The backend is centered in backend/main.py and backend/app.py, with routes defined in backend/api/routes.py.
• backend/schemas/prediction.py defines the request/response shapes using Pydantic.
• backend/core/logging_config.py handles application logging.
• The backend exposes the API endpoints described in the README:
- GET /health
- POST /predict
- POST /analyze
- POST /feedback/{prediction_id}
- GET /feedback/retraining-status
• This layer is the orchestration boundary: it receives requests, coordinates parsing/analysis/inference, and delegates persistence.
3. Resume parsing and explainable analysis services
• backend/services/resume_parser_service.py extracts usable text from uploaded resumes.
• The README indicates support for .txt, .pdf, and .docx, so this service is the file-format boundary between user uploads and downstream analysis.
• backend/services/resume_analysis_service.py computes the explainable scoring layer:
- matched keywords
- missing keywords
- ATS-style score
- semantic similarity score
- final blended score
• This service is where the system’s interpretability lives. It is distinct from the ML model: the model produces a probability/decision, while the analysis service produces human-readable evidence.
4. ML inference layer
• backend/services/model_service.py is the application-facing wrapper around the model.
• The model itself is stored in ml/models/resume_net.pt, with metadata in ml/models/registry/metadata.json.
• The README states the PyTorch model consumes six engineered numeric features:
- years_experience
- skills_match_score
- education_level
- project_count
- resume_length
- github_activity
• This is important architecturally: the model does not operate on raw resume text directly. It sits behind feature extraction and is one part of a hybrid system that combines rule-based analysis with learned classification.
5. Prediction persistence layer
• backend/services/prediction_repository.py is the data-access boundary for SQLite.
• The database file is database/resume_screening.db, and the schema is defined in database/schema.sql.
• The README indicates each prediction record stores:
- prediction probability
- shortlist/reject decision
- threshold used
- source of prediction
- explainability data
- review status and feedback note
• This persistence layer is central to the app’s “adaptive” behavior, because feedback is attached to prior predictions instead of being kept only in memory or logs.
6. Feedback and retraining loop
• feedback_loop/retraining_trigger.py and feedback_loop/adaptive_retrainer.py form the offline adaptation boundary.
• The frontend can mark a prior recommendation as correct or incorrect and optionally attach a note.
• That labeled feedback is stored in the same SQLite database and later consumed by the retraining workflow.
• Architecturally, this is not an always-on training service; it is a deferred pipeline that depends on accumulated feedback.
7. Offline ML development and training pipeline
• The ml/ directory contains the model lifecycle outside the request path:
- ml/data/load_resumes.py for data loading
- ml/preprocessing/preprocess_tabular.py for feature preparation
- ml/training/train_model.py and ml/training/evaluate_model.py for training and evaluation
- ml/inference/resume_screener.py and ml/inference/config.py for inference-time utilities
• Training artifacts are stored under data/processed/, while the raw dataset is in data/raw/ai_resume_screening.csv.
• Notebook files under notebooks/ document exploration, preprocessing, training, and evaluation, but they are not part of the runtime path.
• This separation is important: training is an offline concern, while backend/services/model_service.py consumes the saved checkpoint at runtime.
Primary runtime data flow
A typical screening request moves through the system like this:
• The browser UI sends a resume file plus job description to the backend.
• The backend parses the resume into text.
• The analysis service compares resume content and job description to compute explainability signals.
• A feature vector is assembled for the model from the engineered signals described in the README.
• The PyTorch model generates a prediction probability and classification decision.
• The prediction repository writes the result to SQLite.
• The API response returns both the score and the explanation data to the frontend.
The feedback path is similar but shorter:
• The frontend submits a “correct” or “incorrect” label and optional note for a prior prediction.
• The backend updates the corresponding SQLite record.
• The retraining loop can later query these stored labels to decide whether retraining should occur.
Deployment and environment boundaries
• Local backend execution is centered on FastAPI/Uvicorn.
• Containerization is provided through docker-compose.yml, docker-compose.gpu.yml, and Dockerfiles under docker/.
• docker/nginx.conf suggests an Nginx fronting layer in containerized deployments.
• The repository also includes root-level app.py and main.py, plus public/ assets, to support Vercel deployment.
• The README notes a key deployment distinction: on Vercel, SQLite and model registry writes may default to temporary storage, which means feedback and new artifacts are not durable across cold starts unless persistent storage is configured.
Important architectural characteristics
• It is a hybrid system: heuristic explainability plus ML prediction.
• It uses SQLite as a single local system-of-record for predictions and feedback.
• The runtime path is intentionally lightweight and synchronous, suitable for a demo/prototype.
• Training is decoupled from inference, and notebooks are separated from production code.
• The system is designed to be explainable rather than purely predictive, which affects both the API response shape and the stored data.
If you are drawing an architecture diagram, the clearest boundaries are:
• Browser/UI
• FastAPI application layer
• Parsing and analysis services
• Model inference service
• SQLite repository
• Feedback/retraining loop
• Offline ML training pipeline
• Container/deployment layer
Main entry points: routes.py API routes · model_service.py Model service · index.html Frontend app · prediction_repository.py Prediction repo
Components 21
UI
Browser-facing presentation and static assets
- Frontend app · Primary user interface for uploads, scoring, and feedback
frontend/index.html - Public assets · Deployment-oriented frontend bundle
public/index.html
Backend
FastAPI application layer and request orchestration
- Backend app · Application entrypoint and server bootstrap
backend/main.py - API routes · Predict, analyze, health, and feedback endpoints
backend/api/routes.py - Schemas · Request and response contracts for prediction APIs
backend/schemas/prediction.py - Logging · Central application logging configuration
backend/core/logging_config.py
Services
Parsing, analysis, inference, and persistence services
- Resume parser · Extracts text from uploaded resume files
backend/services/resume_parser_service.py - Analysis service · Computes keywords, ATS-style score, similarity, and blended explanation
backend/services/resume_analysis_service.py - Model service · Application-facing wrapper around the trained PyTorch model
backend/services/model_service.py - Prediction repo · Reads and writes prediction and feedback records
backend/services/prediction_repository.py
Storage
Local database and schema
ML
Offline training and inference artifacts
- Model artifact · Saved resume screening network used at inference time
ml/models/resume_net.pt - Registry metadata · Metadata describing the saved model artifact
ml/models/registry/metadata.json - Training pipeline · Model training and evaluation workflow
ml/training/train_model.py - Preprocessing · Tabular feature preparation for training and inference
ml/preprocessing/preprocess_tabular.py - Inference utils · Runtime helpers for turning engineered features into predictions
ml/inference/resume_screener.py
Feedback
Adaptive retraining loop
- Adaptive retrainer · Consumes stored feedback to trigger retraining
feedback_loop/adaptive_retrainer.py - Retrain trigger · Decides when feedback is sufficient to start retraining
feedback_loop/retraining_trigger.py
Deploy
Container and edge deployment assets
- Docker stack · Compose and Docker deployment definitions
docker-compose.yml - Nginx config · Reverse proxy for containerized deployment
docker/nginx.conf
Connections 24
- Frontend app → API routes: submit resume · Uploads resume and job description to the API
- Public assets → API routes: submit resume · Alternative static frontend path to the same API
- Backend app → API routes: mount routes · Starts the HTTP application and registers endpoints
- API routes → Schemas: validate · Uses request and response schemas for API contracts
- API routes → Resume parser: parse upload · Extracts text from uploaded resume files
- API routes → Analysis service: analyze match · Computes explainable screening signals
- API routes → Model service: infer · Runs the learned classifier on engineered features
- API routes → Prediction repo: persist result · Stores predictions and feedback state
- API routes → Logging: log · Writes request and runtime logs
- Analysis service → Model service: feature signals · Provides engineered inputs for scoring and prediction
- Model service → Model artifact: load model · Loads the saved PyTorch checkpoint
- Model service → Registry metadata: resolve model · Uses registry metadata to identify the active artifact
- Prediction repo → SQLite DB: read/write · Persists prediction records and feedback updates
- SQLite DB → Schema: defined by · Database structure comes from the schema file
- Adaptive retrainer → Prediction repo: consume feedback · Reads labeled prediction history from SQLite
- Adaptive retrainer → Retrain trigger: evaluate · Checks whether retraining should run
- Training pipeline → Preprocessing: prepare data · Transforms raw resume data into training features
- Training pipeline → Model artifact: write checkpoint · Produces the inference-time model artifact
- Preprocessing → Registry metadata: feature spec · Documents the model's feature expectations
- Inference utils → Model artifact: score features · Inference helper around the saved model
- Docker stack → Backend app: run backend · Containerized backend execution
- Docker stack → Frontend app: serve ui · Containerized browser-facing frontend
- Nginx config → Frontend app: proxy static · Edge proxy for static frontend delivery
- Nginx config → API routes: proxy api · Routes API traffic to the backend service