# sr-ntr/cold-start-recommender architecture

> Architecture diagram of the GitHub repository sr-ntr/cold-start-recommender, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sr-ntr/cold-start-recommender
- Repository: https://github.com/sr-ntr/cold-start-recommender

## Overview

This repository is an early-stage, cold-start-aware e-commerce recommendation research project, not yet a serving recommendation system. Its implemented workflow inspects and preprocesses Amazon Electronics interactions, then builds text embeddings from product metadata; the README describes popularity, collaborative, content-based, and hybrid recommendation approaches plus warm/low-history/cold-start evaluation as planned work. Edges reflect the shown preprocessing and embedding calls, or explicit README statements. The data files and recommendation/evaluation implementations are not in the supplied tree.

Main entry points: [`src/features/generate_embeddings.py`](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/generate_embeddings.py) (Embedding generation), [`README.md`](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md) (Recommendation approaches), [`src/data/prepare_interactions.py`](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/data/prepare_interactions.py) (Interaction preparation), [`src/data/inspect_interactions.py`](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/data/inspect_interactions.py) (Interaction inspection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Interaction data"]
  node_raw_interactions["Raw interactions"]
  node_inspect["Interaction inspection"]
  node_prepare["Interaction preparation"]
  node_interaction_parts[("Processed interactions")]
end

subgraph group_embeddings["Product embeddings"]
  node_catalog[("Product catalog")]
  node_metadata["Product metadata"]
  node_metadata_query["Metadata loading"]
  node_text_builder["Product text shaping<br/>[product_text.py]"]
  node_embedding_generator["Embedding generation"]
  node_embedding_model["Sentence transformer"]
  node_embedding_store[("Product embeddings")]
end

subgraph group_roadmap["Recommendation research"]
  node_approaches["Recommendation approaches<br/>[README.md]"]
  node_popularity["Popularity baseline<br/>[README.md]"]
  node_collaborative["Collaborative filtering<br/>[README.md]"]
  node_content_based["Content-based recommendations<br/>[README.md]"]
  node_hybrid["Hybrid recommendations<br/>[README.md]"]
  node_evaluation["Cold-start evaluation<br/>[README.md]"]
end

node_analyst(("Researcher"))

node_analyst -->|"runs"| node_inspect
node_raw_interactions -->|"reads"| node_inspect
node_analyst -->|"runs"| node_prepare
node_raw_interactions -->|"reads"| node_prepare
node_prepare -->|"writes"| node_interaction_parts
node_analyst -->|"runs"| node_embedding_generator
node_embedding_generator -->|"loads"| node_catalog
node_embedding_generator -->|"calls"| node_metadata_query
node_metadata_query -->|"queries"| node_metadata
node_embedding_generator -->|"calls"| node_text_builder
node_embedding_generator -->|"encodes"| node_embedding_model
node_embedding_generator -->|"writes"| node_embedding_store
node_approaches -->|"includes"| node_popularity
node_approaches -->|"includes"| node_collaborative
node_approaches -->|"includes"| node_content_based
node_approaches -->|"includes"| node_hybrid
node_approaches -->|"compares on"| node_evaluation

click node_inspect "https://github.com/sr-ntr/cold-start-recommender/blob/main/src/data/inspect_interactions.py"
click node_prepare "https://github.com/sr-ntr/cold-start-recommender/blob/main/src/data/prepare_interactions.py"
click node_metadata_query "https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/generate_embeddings.py"
click node_text_builder "https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/product_text.py"
click node_embedding_generator "https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/generate_embeddings.py"
click node_approaches "https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md"
click node_popularity "https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md"
click node_collaborative "https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md"
click node_content_based "https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md"
click node_hybrid "https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md"
click node_evaluation "https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md"

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_raw_interactions,node_inspect,node_prepare,node_interaction_parts toneBlue
class node_catalog,node_metadata,node_metadata_query,node_text_builder,node_embedding_generator,node_embedding_model,node_embedding_store toneAmber
class node_approaches,node_popularity,node_collaborative,node_content_based,node_hybrid,node_evaluation toneMint
class node_analyst toneIndigo
```

## Components

### Interaction data

- **Raw interactions**
- [Interaction inspection](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/data/inspect_interactions.py): `src/data/inspect_interactions.py`
- [Interaction preparation](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/data/prepare_interactions.py): `src/data/prepare_interactions.py`
- **Processed interactions**

### Product embeddings

- **Product catalog**
- **Product metadata**
- [Metadata loading](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/generate_embeddings.py): `src/features/generate_embeddings.py`
- [Product text shaping](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/product_text.py): `src/features/product_text.py`
- [Embedding generation](https://github.com/sr-ntr/cold-start-recommender/blob/main/src/features/generate_embeddings.py): `src/features/generate_embeddings.py`
- **Sentence transformer**
- **Product embeddings**

### Recommendation research

- [Recommendation approaches](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md): `README.md`
- [Popularity baseline](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md): `README.md`
- [Collaborative filtering](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md): `README.md`
- [Content-based recommendations](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md): `README.md`
- [Hybrid recommendations](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md): `README.md`
- [Cold-start evaluation](https://github.com/sr-ntr/cold-start-recommender/blob/main/README.md): `README.md`

### Other components

- **Researcher**

## Connections

- Researcher → Interaction inspection: runs (evidence: `src/data/inspect_interactions.py`)
- Raw interactions → Interaction inspection: reads (evidence: `src/data/inspect_interactions.py`)
- Researcher → Interaction preparation: runs (evidence: `src/data/prepare_interactions.py`)
- Raw interactions → Interaction preparation: reads (evidence: `src/data/prepare_interactions.py`)
- Interaction preparation → Processed interactions: writes (evidence: `src/data/prepare_interactions.py`)
- Researcher → Embedding generation: runs (evidence: `src/features/generate_embeddings.py`)
- Embedding generation → Product catalog: loads (evidence: `src/features/generate_embeddings.py`)
- Embedding generation → Metadata loading: calls (evidence: `src/features/generate_embeddings.py`)
- Metadata loading → Product metadata: queries (evidence: `src/features/generate_embeddings.py`)
- Embedding generation → Product text shaping: calls (evidence: `src/features/generate_embeddings.py`)
- Embedding generation → Sentence transformer: encodes (evidence: `src/features/generate_embeddings.py`)
- Embedding generation → Product embeddings: writes (evidence: `src/features/generate_embeddings.py`)
- Recommendation approaches → Popularity baseline: includes (evidence: `README.md`)
- Recommendation approaches → Collaborative filtering: includes (evidence: `README.md`)
- Recommendation approaches → Content-based recommendations: includes (evidence: `README.md`)
- Recommendation approaches → Hybrid recommendations: includes (evidence: `README.md`)
- Recommendation approaches → Cold-start evaluation: compares on (evidence: `README.md`)
