# lawk-0/adaptive-resume-screener architecture

> Architecture diagram of the GitHub repository lawk-0/adaptive-resume-screener, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lawk-0/adaptive-resume-screener
- Repository: https://github.com/lawk-0/adaptive-resume-screener

## Overview

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: [`backend/api/routes.py`](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/api/routes.py) (API routes), [`backend/services/model_service.py`](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/model_service.py) (Model service), [`frontend/index.html`](https://github.com/lawk-0/adaptive-resume-screener/blob/main/frontend/index.html) (Frontend app), [`backend/services/prediction_repository.py`](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/prediction_repository.py) (Prediction repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_frontend_ui["Frontend app<br/>browser UI<br/>[index.html]"]
  node_public_assets["Public assets<br/>static UI<br/>[index.html]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Backend app<br/>FastAPI app<br/>[main.py]"]
  node_backend_routes["API routes<br/>HTTP routes<br/>[routes.py]"]
  node_backend_models["Schemas<br/>Pydantic models<br/>[prediction.py]"]
  node_logging_config["Logging<br/>app config<br/>[logging_config.py]"]
end

subgraph group_services["Services"]
  node_parser_service["Resume parser<br/>file parsing"]
  node_analysis_service["Analysis service<br/>scoring logic"]
  node_model_service["Model service<br/>inference wrapper<br/>[model_service.py]"]
  node_repo_service["Prediction repo<br/>SQLite access"]
end

subgraph group_storage["Storage"]
  node_db_file[("SQLite DB<br/>local database")]
  node_db_schema["Schema<br/>DDL<br/>[schema.sql]"]
end

subgraph group_ml["ML"]
  node_model_artifact["Model artifact<br/>PyTorch checkpoint<br/>[resume_net.pt]"]
  node_model_metadata["Registry metadata<br/>model registry<br/>[metadata.json]"]
  node_train_pipeline["Training pipeline<br/>offline ML<br/>[train_model.py]"]
  node_preprocess_pipeline["Preprocessing<br/>feature prep"]
  node_resume_screener["Inference utils<br/>ml inference<br/>[resume_screener.py]"]
end

subgraph group_feedback["Feedback"]
  node_retrainer["Adaptive retrainer<br/>feedback loop"]
  node_trigger["Retrain trigger<br/>policy"]
end

subgraph group_deploy["Deploy"]
  node_docker_stack["Docker stack<br/>containerization<br/>[docker-compose.yml]"]
  node_nginx_config["Nginx config<br/>edge proxy<br/>[nginx.conf]"]
end

node_frontend_ui -->|"submit resume"| node_backend_routes
node_public_assets -->|"submit resume"| node_backend_routes
node_backend_entry -->|"mount routes"| node_backend_routes
node_backend_routes -->|"validate"| node_backend_models
node_backend_routes -->|"parse upload"| node_parser_service
node_backend_routes -->|"analyze match"| node_analysis_service
node_backend_routes -->|"infer"| node_model_service
node_backend_routes -->|"persist result"| node_repo_service
node_backend_routes -->|"log"| node_logging_config
node_analysis_service -->|"feature signals"| node_model_service
node_model_service -->|"load model"| node_model_artifact
node_model_service -->|"resolve model"| node_model_metadata
node_repo_service -->|"read/write"| node_db_file
node_db_file -->|"defined by"| node_db_schema
node_retrainer -->|"consume feedback"| node_repo_service
node_retrainer -->|"evaluate"| node_trigger
node_train_pipeline -->|"prepare data"| node_preprocess_pipeline
node_train_pipeline -->|"write checkpoint"| node_model_artifact
node_preprocess_pipeline -->|"feature spec"| node_model_metadata
node_resume_screener -->|"score features"| node_model_artifact
node_docker_stack -->|"run backend"| node_backend_entry
node_docker_stack -->|"serve ui"| node_frontend_ui
node_nginx_config -->|"proxy static"| node_frontend_ui
node_nginx_config -->|"proxy api"| node_backend_routes

click node_frontend_ui "https://github.com/lawk-0/adaptive-resume-screener/blob/main/frontend/index.html"
click node_public_assets "https://github.com/lawk-0/adaptive-resume-screener/blob/main/public/index.html"
click node_backend_entry "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/main.py"
click node_backend_routes "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/api/routes.py"
click node_backend_models "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/schemas/prediction.py"
click node_logging_config "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/core/logging_config.py"
click node_parser_service "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/resume_parser_service.py"
click node_analysis_service "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/resume_analysis_service.py"
click node_model_service "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/model_service.py"
click node_repo_service "https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/prediction_repository.py"
click node_db_file "https://github.com/lawk-0/adaptive-resume-screener/blob/main/database/resume_screening.db"
click node_db_schema "https://github.com/lawk-0/adaptive-resume-screener/blob/main/database/schema.sql"
click node_model_artifact "https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/models/resume_net.pt"
click node_model_metadata "https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/models/registry/metadata.json"
click node_train_pipeline "https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/training/train_model.py"
click node_preprocess_pipeline "https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/preprocessing/preprocess_tabular.py"
click node_resume_screener "https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/inference/resume_screener.py"
click node_retrainer "https://github.com/lawk-0/adaptive-resume-screener/blob/main/feedback_loop/adaptive_retrainer.py"
click node_trigger "https://github.com/lawk-0/adaptive-resume-screener/blob/main/feedback_loop/retraining_trigger.py"
click node_docker_stack "https://github.com/lawk-0/adaptive-resume-screener/blob/main/docker-compose.yml"
click node_nginx_config "https://github.com/lawk-0/adaptive-resume-screener/blob/main/docker/nginx.conf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_ui,node_public_assets,node_docker_stack,node_nginx_config toneBlue
class node_backend_entry,node_backend_routes,node_backend_models,node_logging_config toneAmber
class node_parser_service,node_analysis_service,node_model_service,node_repo_service toneMint
class node_db_file,node_db_schema toneRose
class node_model_artifact,node_model_metadata,node_train_pipeline,node_preprocess_pipeline,node_resume_screener toneIndigo
class node_retrainer,node_trigger toneTeal
```

## Components

### UI

Browser-facing presentation and static assets

- [Frontend app](https://github.com/lawk-0/adaptive-resume-screener/blob/main/frontend/index.html): browser UI · Primary user interface for uploads, scoring, and feedback · `frontend/index.html`
- [Public assets](https://github.com/lawk-0/adaptive-resume-screener/blob/main/public/index.html): static UI · Deployment-oriented frontend bundle · `public/index.html`

### Backend

FastAPI application layer and request orchestration

- [Backend app](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/main.py): FastAPI app · Application entrypoint and server bootstrap · `backend/main.py`
- [API routes](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/api/routes.py): HTTP routes · Predict, analyze, health, and feedback endpoints · `backend/api/routes.py`
- [Schemas](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/schemas/prediction.py): Pydantic models · Request and response contracts for prediction APIs · `backend/schemas/prediction.py`
- [Logging](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/core/logging_config.py): app config · Central application logging configuration · `backend/core/logging_config.py`

### Services

Parsing, analysis, inference, and persistence services

- [Resume parser](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/resume_parser_service.py): file parsing · Extracts text from uploaded resume files · `backend/services/resume_parser_service.py`
- [Analysis service](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/resume_analysis_service.py): scoring logic · Computes keywords, ATS-style score, similarity, and blended explanation · `backend/services/resume_analysis_service.py`
- [Model service](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/model_service.py): inference wrapper · Application-facing wrapper around the trained PyTorch model · `backend/services/model_service.py`
- [Prediction repo](https://github.com/lawk-0/adaptive-resume-screener/blob/main/backend/services/prediction_repository.py): SQLite access · Reads and writes prediction and feedback records · `backend/services/prediction_repository.py`

### Storage

Local database and schema

- [SQLite DB](https://github.com/lawk-0/adaptive-resume-screener/blob/main/database/resume_screening.db): local database · Persistent store for predictions and feedback · `database/resume_screening.db`
- [Schema](https://github.com/lawk-0/adaptive-resume-screener/blob/main/database/schema.sql): DDL · Database schema definition · `database/schema.sql`

### ML

Offline training and inference artifacts

- [Model artifact](https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/models/resume_net.pt): PyTorch checkpoint · Saved resume screening network used at inference time · `ml/models/resume_net.pt`
- [Registry metadata](https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/models/registry/metadata.json): model registry · Metadata describing the saved model artifact · `ml/models/registry/metadata.json`
- [Training pipeline](https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/training/train_model.py): offline ML · Model training and evaluation workflow · `ml/training/train_model.py`
- [Preprocessing](https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/preprocessing/preprocess_tabular.py): feature prep · Tabular feature preparation for training and inference · `ml/preprocessing/preprocess_tabular.py`
- [Inference utils](https://github.com/lawk-0/adaptive-resume-screener/blob/main/ml/inference/resume_screener.py): ml inference · Runtime helpers for turning engineered features into predictions · `ml/inference/resume_screener.py`

### Feedback

Adaptive retraining loop

- [Adaptive retrainer](https://github.com/lawk-0/adaptive-resume-screener/blob/main/feedback_loop/adaptive_retrainer.py): feedback loop · Consumes stored feedback to trigger retraining · `feedback_loop/adaptive_retrainer.py`
- [Retrain trigger](https://github.com/lawk-0/adaptive-resume-screener/blob/main/feedback_loop/retraining_trigger.py): policy · Decides when feedback is sufficient to start retraining · `feedback_loop/retraining_trigger.py`

### Deploy

Container and edge deployment assets

- [Docker stack](https://github.com/lawk-0/adaptive-resume-screener/blob/main/docker-compose.yml): containerization · Compose and Docker deployment definitions · `docker-compose.yml`
- [Nginx config](https://github.com/lawk-0/adaptive-resume-screener/blob/main/docker/nginx.conf): edge proxy · Reverse proxy for containerized deployment · `docker/nginx.conf`

## Connections

- 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
