# thimmareddygt7/ranking_recommendation_system architecture

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

- Interactive diagram: https://gitdiagram.com/thimmareddygt7/ranking_recommendation_system
- Repository: https://github.com/thimmareddygt7/ranking_recommendation_system

## Overview

This Retailrocket recommender serves personalized top-k items through candidate selection, LambdaMART re-ranking, and a popularity fallback for cold-start users. Offline capabilities also include interaction cleaning and chronological splitting, feature construction, ALS and popularity retrieval training, ranking evaluation, error analysis, and PSI score-drift checks. The API source shows artifact loading and recommendation dispatch; training and evaluation relationships are documented in the README but their full orchestration is not sampled, so those links are omitted. The README also describes session signals, though their use in serving is not demonstrated in the excerpts.

Main entry points: [`serving/main.py`](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py) (Recommendation API), [`src/evaluation/error_analysis.py`](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/evaluation/error_analysis.py) (Ranking Error Analysis), [`src/monitoring/drift_check.py`](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/monitoring/drift_check.py) (Score Drift Check), [`src/retrieval/candidate_generator.py`](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/retrieval/candidate_generator.py) (ALS & Popularity Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline Modeling"]
  node_clean["Event Cleaning &amp; Split<br/>[clean.py]"]
  node_features["User &amp; Item Features<br/>[build_features.py]"]
  node_session_features["Session Signals"]
  node_retrieval_train["ALS &amp; Popularity Training"]
  node_ranking_train["Ranker Training<br/>[train.py]"]
  node_pipeline["Pipeline Status Runner<br/>[pipeline.py]"]
end

subgraph group_serving["Recommendation Serving"]
  node_api["Recommendation API<br/>[main.py]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
  node_candidate_store[("Candidate Store<br/>[main.py]")]
  node_item_profiles[("Item Profiles<br/>[main.py]")]
  node_ranker["LambdaMART Ranker<br/>[main.py]"]
  node_cold_handler["Cold-start Handler<br/>[cold_start.py]"]
end

subgraph group_quality["Evaluation &amp; Monitoring"]
  node_segment_eval["Segment Evaluation"]
  node_error_analysis["Ranking Error Analysis<br/>[error_analysis.py]"]
  node_drift["Score Drift Check<br/>[drift_check.py]"]
end

node_user(("Shopper"))
node_models[("Model Artifacts")]
node_processed[("Processed Ranking Data")]
node_results[("Evaluation Results")]

node_user -->|"requests recommendations"| node_api
node_api -->|"validates requests"| node_schemas
node_api -->|"requests fallback"| node_cold_handler
node_cold_handler -->|"loads popularity baseline"| node_models
node_api -->|"loads candidates"| node_candidate_store
node_api -->|"reads ranking dataset"| node_processed
node_api -->|"builds profiles"| node_item_profiles
node_api -->|"predicts scores"| node_ranker
node_api -->|"loads ranker artifact"| node_models
node_clean -.->|"writes event splits"| node_processed
node_features -.->|"builds ranking features"| node_processed
node_session_features -.->|"extracts session signals"| node_features
node_retrieval_train -->|"reads events; writes candidates"| node_processed
node_retrieval_train -->|"saves ALS and popularity"| node_models
node_ranking_train -->|"reads ranking and test data"| node_processed
node_ranking_train -->|"saves ranker"| node_models
node_pipeline -->|"checks model artifacts"| node_models
node_pipeline -->|"writes status summary"| node_results
node_segment_eval -.->|"reports segments"| node_results
node_error_analysis -->|"reads ranking and test data"| node_processed
node_error_analysis -->|"loads ranker"| node_models
node_error_analysis -->|"writes failure report"| node_results
node_drift -->|"reads ranking and test data"| node_processed
node_drift -->|"loads ranker"| node_models
node_drift -->|"reports PSI status"| node_results

click node_api "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py"
click node_schemas "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/schemas.py"
click node_candidate_store "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py"
click node_item_profiles "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py"
click node_ranker "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py"
click node_cold_handler "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/cold_start.py"
click node_clean "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/data/clean.py"
click node_features "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/features/build_features.py"
click node_session_features "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/features/session_features.py"
click node_retrieval_train "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/retrieval/candidate_generator.py"
click node_ranking_train "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/ranking/train.py"
click node_pipeline "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/pipeline.py"
click node_segment_eval "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/evaluation/segment_analysis.py"
click node_error_analysis "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/evaluation/error_analysis.py"
click node_drift "https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/monitoring/drift_check.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_clean,node_features,node_session_features,node_retrieval_train,node_ranking_train,node_pipeline toneBlue
class node_api,node_schemas,node_candidate_store,node_item_profiles,node_ranker,node_cold_handler,node_models,node_processed,node_results toneAmber
class node_segment_eval,node_error_analysis,node_drift toneMint
class node_user toneIndigo
```

## Components

### Offline Modeling

- [Event Cleaning & Split](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/data/clean.py): `src/data/clean.py`
- [User & Item Features](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/features/build_features.py): `src/features/build_features.py`
- [Session Signals](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/features/session_features.py): `src/features/session_features.py`
- [ALS & Popularity Training](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/retrieval/candidate_generator.py): `src/retrieval/candidate_generator.py`
- [Ranker Training](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/ranking/train.py): `src/ranking/train.py`
- [Pipeline Status Runner](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/pipeline.py): `src/pipeline.py`

### Recommendation Serving

- [Recommendation API](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py): `serving/main.py`
- [Request Schemas](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/schemas.py): `serving/schemas.py`
- [Candidate Store](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py): `serving/main.py`
- [Item Profiles](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py): `serving/main.py`
- [LambdaMART Ranker](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/main.py): `serving/main.py`
- [Cold-start Handler](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/serving/cold_start.py): `serving/cold_start.py`

### Evaluation & Monitoring

- [Segment Evaluation](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/evaluation/segment_analysis.py): `src/evaluation/segment_analysis.py`
- [Ranking Error Analysis](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/evaluation/error_analysis.py): `src/evaluation/error_analysis.py`
- [Score Drift Check](https://github.com/thimmareddygt7/ranking_recommendation_system/blob/main/src/monitoring/drift_check.py): `src/monitoring/drift_check.py`

### Other components

- **Shopper**
- **Model Artifacts**
- **Processed Ranking Data**
- **Evaluation Results**

## Connections

- Shopper → Recommendation API: requests recommendations (evidence: `README.md`)
- Recommendation API → Request Schemas: validates requests (evidence: `serving/main.py`)
- Recommendation API → Cold-start Handler: requests fallback (evidence: `serving/main.py`)
- Cold-start Handler → Model Artifacts: loads popularity baseline (evidence: `serving/cold_start.py`)
- Recommendation API → Candidate Store: loads candidates (evidence: `serving/main.py`)
- Recommendation API → Processed Ranking Data: reads ranking dataset (evidence: `serving/main.py`)
- Recommendation API → Item Profiles: builds profiles (evidence: `serving/main.py`)
- Recommendation API → LambdaMART Ranker: predicts scores (evidence: `serving/main.py`)
- Recommendation API → Model Artifacts: loads ranker artifact (evidence: `serving/main.py`)
- Event Cleaning & Split → Processed Ranking Data: writes event splits (evidence: `README.md`)
- User & Item Features → Processed Ranking Data: builds ranking features (evidence: `README.md`)
- Session Signals → User & Item Features: extracts session signals (evidence: `README.md`)
- ALS & Popularity Training → Processed Ranking Data: reads events; writes candidates (evidence: `README.md`)
- ALS & Popularity Training → Model Artifacts: saves ALS and popularity (evidence: `src/retrieval/candidate_generator.py`)
- Ranker Training → Processed Ranking Data: reads ranking and test data (evidence: `src/ranking/train.py`)
- Ranker Training → Model Artifacts: saves ranker (evidence: `src/ranking/train.py`)
- Pipeline Status Runner → Model Artifacts: checks model artifacts (evidence: `src/pipeline.py`)
- Pipeline Status Runner → Evaluation Results: writes status summary (evidence: `src/pipeline.py`)
- Segment Evaluation → Evaluation Results: reports segments (evidence: `README.md`)
- Ranking Error Analysis → Processed Ranking Data: reads ranking and test data (evidence: `src/evaluation/error_analysis.py`)
- Ranking Error Analysis → Model Artifacts: loads ranker (evidence: `src/evaluation/error_analysis.py`)
- Ranking Error Analysis → Evaluation Results: writes failure report (evidence: `src/evaluation/error_analysis.py`)
- Score Drift Check → Processed Ranking Data: reads ranking and test data (evidence: `src/monitoring/drift_check.py`)
- Score Drift Check → Model Artifacts: loads ranker (evidence: `src/monitoring/drift_check.py`)
- Score Drift Check → Evaluation Results: reports PSI status (evidence: `README.md`)