# neeleshpanchumarthi/fashion-recommender-system architecture

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

- Interactive diagram: https://gitdiagram.com/neeleshpanchumarthi/fashion-recommender-system
- Repository: https://github.com/neeleshpanchumarthi/fashion-recommender-system

## Overview

StyleIQ is a fashion discovery product with a React client, a FastAPI search/try-on API, and a separate offline catalog-ingestion worker. The main shopping flow turns a natural-language query into understood filters, retrieves and reranks products, then returns results for display; outfit-aware and multilingual search extend that flow. Separate branches provide asynchronous virtual try-on, review insights, and index preparation. The graph follows documented flows and indexed source references; some frontend/API wiring and unsampled subsystems are linked only where the README documents them.

Main entry points: [`workers/ingestion_worker.py`](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/ingestion_worker.py) (Ingestion worker), [`app/retrieval/pipeline.py`](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/pipeline.py) (Retrieval pipeline), [`frontend/src/hooks/useSearch.ts`](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/hooks/useSearch.ts) (Search experience), [`frontend/src/services/apiClient.ts`](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/services/apiClient.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Shopping frontend"]
  node_frontend["React app<br/>[App.tsx]"]
  node_search_ui["Search experience<br/>[useSearch.ts]"]
  node_results_ui["Product results<br/>[SearchResults.tsx]"]
  node_tryon_ui["Try-on dialog<br/>[TryOnDialog.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
end

subgraph group_api["API and services"]
  node_api_router["API routes<br/>[router.py]"]
  node_search_route["Search endpoint<br/>[search.py]"]
  node_search_service["Search service<br/>[search_service.py]"]
  node_tryon_route["Try-on endpoint<br/>[tryon.py]"]
  node_tryon_service["Try-on jobs<br/>[tryon_service.py]"]
  node_review_insights["Review insights"]
end

subgraph group_search["Search and domain"]
  node_pipeline["Retrieval pipeline<br/>[pipeline.py]"]
  node_query_understanding["Query understanding<br/>[query_processor.py]"]
  node_retriever["Dense retrieval<br/>[retriever.py]"]
  node_reranker["Result reranking<br/>[reranker.py]"]
  node_vector_repo["Vector repository"]
  node_embedder["Text embeddings"]
end

subgraph group_ingest["Catalog ingestion"]
  node_dataset["Dataset access"]
  node_worker["Ingestion worker"]
  node_review_analysis["Review analysis"]
  node_batching["Batch processing<br/>[batch_processor.py]"]
  node_checkpoint["Checkpointing"]
end

subgraph group_integrations["External systems"]
  node_llm["Groq LLM<br/>[llm_client.py]"]
  node_pinecone[("Pinecone index<br/>[pinecone_client.py]")]
  node_sentiment["Sentiment model"]
  node_tryon_provider["Hugging Face Space<br/>[tryon_client.py]"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_frontend
node_frontend -.->|"renders"| node_search_ui
node_search_ui -->|"requests search"| node_api_client
node_api_client -->|"calls API"| node_search_route
node_api_router -->|"routes to"| node_search_route
node_search_route -->|"calls"| node_search_service
node_search_service -->|"runs"| node_pipeline
node_pipeline -->|"processes query"| node_query_understanding
node_query_understanding -->|"understands query"| node_llm
node_pipeline -->|"embeds query"| node_embedder
node_pipeline -->|"retrieves candidates"| node_retriever
node_retriever -->|"searches vectors"| node_vector_repo
node_vector_repo -->|"queries index"| node_pinecone
node_pipeline -->|"reranks candidates"| node_reranker
node_pipeline -.->|"returns results"| node_search_service
node_search_ui -.->|"shows results"| node_results_ui
node_api_router -->|"routes to"| node_tryon_route
node_tryon_route -->|"submits or polls"| node_tryon_service
node_tryon_service -->|"runs try-on"| node_tryon_provider
node_tryon_ui -.->|"uses API"| node_api_client
node_worker -->|"loads catalog"| node_dataset
node_worker -->|"processes batches"| node_batching
node_worker -->|"analyzes reviews"| node_review_analysis
node_review_analysis -->|"classifies reviews"| node_sentiment
node_worker -->|"embeds products"| node_embedder
node_worker -->|"upserts vectors"| node_vector_repo
node_worker -->|"records progress"| node_checkpoint
node_review_insights -.->|"uses analysis"| node_review_analysis

click node_frontend "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/App.tsx"
click node_search_ui "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/hooks/useSearch.ts"
click node_results_ui "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/pages/SearchResults.tsx"
click node_tryon_ui "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/components/tryon/TryOnDialog.tsx"
click node_api_client "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/services/apiClient.ts"
click node_api_router "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/api/router.py"
click node_search_route "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/api/routes/search.py"
click node_search_service "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/search_service.py"
click node_tryon_route "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/api/routes/tryon.py"
click node_tryon_service "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/tryon_service.py"
click node_review_insights "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/product_enrichment_service.py"
click node_pipeline "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/pipeline.py"
click node_query_understanding "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/query_processor.py"
click node_retriever "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/retriever.py"
click node_reranker "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/reranker.py"
click node_vector_repo "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/repositories/vector_repository.py"
click node_embedder "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/embedding_client.py"
click node_dataset "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/repositories/dataset_repository.py"
click node_worker "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/ingestion_worker.py"
click node_review_analysis "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/review_analysis_service.py"
click node_batching "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/batch_processor.py"
click node_checkpoint "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/checkpoint_manager.py"
click node_llm "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/llm_client.py"
click node_pinecone "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/pinecone_client.py"
click node_sentiment "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/sentiment_client.py"
click node_tryon_provider "https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/tryon_client.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_frontend,node_search_ui,node_results_ui,node_tryon_ui,node_api_client toneBlue
class node_api_router,node_search_route,node_search_service,node_tryon_route,node_tryon_service,node_review_insights toneAmber
class node_pipeline,node_query_understanding,node_retriever,node_reranker,node_vector_repo,node_embedder toneMint
class node_dataset,node_worker,node_review_analysis,node_batching,node_checkpoint toneRose
class node_llm,node_pinecone,node_sentiment,node_tryon_provider,node_shopper toneIndigo
```

## Components

### Shopping frontend

- [React app](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Search experience](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/hooks/useSearch.ts): `frontend/src/hooks/useSearch.ts`
- [Product results](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/pages/SearchResults.tsx): `frontend/src/pages/SearchResults.tsx`
- [Try-on dialog](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/components/tryon/TryOnDialog.tsx): `frontend/src/components/tryon/TryOnDialog.tsx`
- [API client](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### API and services

- [API routes](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/api/router.py): `app/api/router.py`
- [Search endpoint](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/api/routes/search.py): `app/api/routes/search.py`
- [Search service](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/search_service.py): `app/services/search_service.py`
- [Try-on endpoint](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/api/routes/tryon.py): `app/api/routes/tryon.py`
- [Try-on jobs](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/tryon_service.py): `app/services/tryon_service.py`
- [Review insights](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/product_enrichment_service.py): `app/services/product_enrichment_service.py`

### Search and domain

- [Retrieval pipeline](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/pipeline.py): `app/retrieval/pipeline.py`
- [Query understanding](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/query_processor.py): `app/retrieval/query_processor.py`
- [Dense retrieval](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/retriever.py): `app/retrieval/retriever.py`
- [Result reranking](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/retrieval/reranker.py): `app/retrieval/reranker.py`
- [Vector repository](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/repositories/vector_repository.py): `app/repositories/vector_repository.py`
- [Text embeddings](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/embedding_client.py): `app/clients/embedding_client.py`

### Catalog ingestion

- [Dataset access](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/repositories/dataset_repository.py): `app/repositories/dataset_repository.py`
- [Ingestion worker](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/ingestion_worker.py): `workers/ingestion_worker.py`
- [Review analysis](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/services/review_analysis_service.py): `app/services/review_analysis_service.py`
- [Batch processing](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/batch_processor.py): `workers/batch_processor.py`
- [Checkpointing](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/workers/checkpoint_manager.py): `workers/checkpoint_manager.py`

### External systems

- [Groq LLM](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/llm_client.py): `app/clients/llm_client.py`
- [Pinecone index](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/pinecone_client.py): `app/clients/pinecone_client.py`
- [Sentiment model](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/sentiment_client.py): `app/clients/sentiment_client.py`
- [Hugging Face Space](https://github.com/neeleshpanchumarthi/fashion-recommender-system/blob/main/app/clients/tryon_client.py): `app/clients/tryon_client.py`

### Other components

- **Shopper**

## Connections

- Shopper → React app: uses (evidence: `README.md`)
- React app → Search experience: renders
- Search experience → API client: requests search (evidence: `README.md`)
- API client → Search endpoint: calls API (evidence: `README.md`)
- API routes → Search endpoint: routes to (evidence: `app/api/router.py`)
- Search endpoint → Search service: calls (evidence: `app/api/routes/search.py`)
- Search service → Retrieval pipeline: runs (evidence: `app/services/search_service.py`)
- Retrieval pipeline → Query understanding: processes query (evidence: `app/retrieval/pipeline.py`)
- Query understanding → Groq LLM: understands query (evidence: `app/retrieval/query_processor.py`)
- Retrieval pipeline → Text embeddings: embeds query (evidence: `app/retrieval/pipeline.py`)
- Retrieval pipeline → Dense retrieval: retrieves candidates (evidence: `app/retrieval/pipeline.py`)
- Dense retrieval → Vector repository: searches vectors (evidence: `app/retrieval/retriever.py`)
- Vector repository → Pinecone index: queries index (evidence: `app/repositories/vector_repository.py`)
- Retrieval pipeline → Result reranking: reranks candidates (evidence: `app/retrieval/pipeline.py`)
- Retrieval pipeline → Search service: returns results (evidence: `app/services/search_service.py`)
- Search experience → Product results: shows results
- API routes → Try-on endpoint: routes to (evidence: `app/api/router.py`)
- Try-on endpoint → Try-on jobs: submits or polls (evidence: `app/api/routes/tryon.py`)
- Try-on jobs → Hugging Face Space: runs try-on (evidence: `app/services/tryon_service.py`)
- Try-on dialog → API client: uses API
- Ingestion worker → Dataset access: loads catalog (evidence: `workers/ingestion_worker.py`)
- Ingestion worker → Batch processing: processes batches (evidence: `workers/ingestion_worker.py`)
- Ingestion worker → Review analysis: analyzes reviews (evidence: `workers/ingestion_worker.py`)
- Review analysis → Sentiment model: classifies reviews (evidence: `app/services/review_analysis_service.py`)
- Ingestion worker → Text embeddings: embeds products (evidence: `workers/ingestion_worker.py`)
- Ingestion worker → Vector repository: upserts vectors (evidence: `workers/ingestion_worker.py`)
- Ingestion worker → Checkpointing: records progress (evidence: `workers/ingestion_worker.py`)
- Review insights → Review analysis: uses analysis
