# younessshr/xxrec-ai-matching architecture

> Architecture diagram of the GitHub repository younessshr/xxrec-ai-matching, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/younessshr/xxrec-ai-matching
- Repository: https://github.com/younessshr/xxrec-ai-matching

## Overview

XXREC is an AI-assisted candidate–job matching service. Its primary workflow accepts a base64 PDF CV, extracts and redacts text, parses a structured profile, computes candidate–requisition features, and returns a LightGBM match score. Separate endpoints provide SHAP-backed explanations and personalized technical tests. The repository also contains an offline synthetic-data and model-training workflow. README_SETUP.md and DEPLOYMENT_GUIDE.md are present in the tree, but no README content or excerpts documenting additional capabilities were provided; connections below rely on the shown source and SOURCE INDEX.

Main entry points: [`api/main.py`](https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py) (FastAPI endpoints), [`src/llm/ai_pipeline.py`](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/llm/ai_pipeline.py) (Gemini pipeline), [`data/model_lgbm.pkl`](https://github.com/younessshr/xxrec-ai-matching/blob/main/data/model_lgbm.pkl) (LightGBM model artifact), [`src/ml/build_features.py`](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/build_features.py) (Dataset feature engineering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Matching API"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_pdf["PDF text extraction<br/>[main.py]"]
  node_features_live["Live feature computation<br/>[main.py]"]
  node_shap["SHAP explainer<br/>[main.py]"]
end

subgraph group_ai["LLM features"]
  node_redaction["PII redaction<br/>[redact.py]"]
  node_ai_pipeline["Gemini pipeline<br/>[ai_pipeline.py]"]
end

subgraph group_ml["Model workflow"]
  node_dataset["Synthetic data generation"]
  node_feature_build["Dataset feature engineering<br/>[build_features.py]"]
  node_training["Model training and ranking evaluation<br/>[train_model.py]"]
  node_offline_explain["Offline SHAP analysis<br/>[explain_model.py]"]
end

subgraph group_artifacts["Model artifacts"]
  node_model["LightGBM model artifact<br/>[model_lgbm.pkl]"]
end

node_client(("API client"))
node_gemini["Google Gemini"]

node_client -->|"sends requests"| node_api
node_api -->|"extracts PDF text"| node_pdf
node_api -->|"parses CV"| node_ai_pipeline
node_ai_pipeline -->|"redacts text"| node_redaction
node_ai_pipeline -->|"requests generation"| node_gemini
node_api -->|"computes features"| node_features_live
node_api -->|"predicts scores"| node_model
node_api -->|"computes contributions"| node_shap
node_api -->|"generates explanations"| node_ai_pipeline
node_api -->|"generates tests"| node_ai_pipeline
node_dataset -->|"writes matching dataset"| node_feature_build
node_feature_build -->|"writes feature dataset"| node_training
node_training -->|"saves model"| node_model
node_offline_explain -->|"loads model"| node_model
node_api -->|"returns results"| node_client

click node_api "https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py"
click node_pdf "https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py"
click node_features_live "https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py"
click node_redaction "https://github.com/younessshr/xxrec-ai-matching/blob/main/src/llm/redact.py"
click node_ai_pipeline "https://github.com/younessshr/xxrec-ai-matching/blob/main/src/llm/ai_pipeline.py"
click node_dataset "https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/generate_dataset.py"
click node_feature_build "https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/build_features.py"
click node_training "https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/train_model.py"
click node_offline_explain "https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/explain_model.py"
click node_model "https://github.com/younessshr/xxrec-ai-matching/blob/main/data/model_lgbm.pkl"
click node_shap "https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py"

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_api,node_pdf,node_features_live,node_shap,node_client toneBlue
class node_redaction,node_ai_pipeline toneAmber
class node_dataset,node_feature_build,node_training,node_offline_explain toneMint
class node_model toneRose
class node_gemini toneIndigo
```

## Components

### Matching API

- [FastAPI endpoints](https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py): `api/main.py`
- [PDF text extraction](https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py): `api/main.py`
- [Live feature computation](https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py): `api/main.py`
- [SHAP explainer](https://github.com/younessshr/xxrec-ai-matching/blob/main/api/main.py): `api/main.py`

### LLM features

- [PII redaction](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/llm/redact.py): `src/llm/redact.py`
- [Gemini pipeline](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/llm/ai_pipeline.py): `src/llm/ai_pipeline.py`

### Model workflow

- [Synthetic data generation](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/generate_dataset.py): `src/ml/generate_dataset.py`
- [Dataset feature engineering](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/build_features.py): `src/ml/build_features.py`
- [Model training and ranking evaluation](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/train_model.py): `src/ml/train_model.py`
- [Offline SHAP analysis](https://github.com/younessshr/xxrec-ai-matching/blob/main/src/ml/explain_model.py): `src/ml/explain_model.py`

### Model artifacts

- [LightGBM model artifact](https://github.com/younessshr/xxrec-ai-matching/blob/main/data/model_lgbm.pkl): `data/model_lgbm.pkl`

### Other components

- **API client**
- **Google Gemini**

## Connections

- API client → FastAPI endpoints: sends requests (evidence: `api/main.py`)
- FastAPI endpoints → PDF text extraction: extracts PDF text (evidence: `api/main.py`)
- FastAPI endpoints → Gemini pipeline: parses CV (evidence: `api/main.py`)
- Gemini pipeline → PII redaction: redacts text (evidence: `src/llm/ai_pipeline.py`)
- Gemini pipeline → Google Gemini: requests generation (evidence: `src/llm/ai_pipeline.py`)
- FastAPI endpoints → Live feature computation: computes features (evidence: `api/main.py`)
- FastAPI endpoints → LightGBM model artifact: predicts scores (evidence: `api/main.py`)
- FastAPI endpoints → SHAP explainer: computes contributions (evidence: `api/main.py`)
- FastAPI endpoints → Gemini pipeline: generates explanations (evidence: `api/main.py`)
- FastAPI endpoints → Gemini pipeline: generates tests (evidence: `api/main.py`)
- Synthetic data generation → Dataset feature engineering: writes matching dataset (evidence: `src/ml/generate_dataset.py`)
- Dataset feature engineering → Model training and ranking evaluation: writes feature dataset (evidence: `src/ml/build_features.py`)
- Model training and ranking evaluation → LightGBM model artifact: saves model (evidence: `src/ml/train_model.py`)
- Offline SHAP analysis → LightGBM model artifact: loads model (evidence: `src/ml/explain_model.py`)
- FastAPI endpoints → API client: returns results (evidence: `api/main.py`)