# 522blackcat/appleproductrag architecture

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

- Interactive diagram: https://gitdiagram.com/522blackcat/appleproductrag
- Repository: https://github.com/522blackcat/appleproductrag

## Overview

AppleProductRag builds a local FAISS index from Apple product Markdown, then answers user queries through constrained vector retrieval, reranking, and an LLM. The map includes the documented year/month/color/category filters and product metadata (including prices, images, and document paths). Source excerpts establish the main calls; the documented workflow supplies the fallback behavior. Product-document maintenance scripts are omitted as supporting utilities.

Main entry points: [`search_index.py`](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py) (Query workflow), [`build_index.py`](https://github.com/522blackcat/appleproductrag/blob/main/build_index.py) (Index builder), [`rag_common.py`](https://github.com/522blackcat/appleproductrag/blob/main/rag_common.py) (Embedding model), [`faiss_index`](https://github.com/522blackcat/appleproductrag/tree/main/faiss_index) (FAISS index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Product corpus and index"]
  node_product_docs["Product documents"]
  node_index_builder["Index builder<br/>[build_index.py]"]
  node_embedding["Embedding model<br/>[rag_common.py]"]
  node_faiss[("FAISS index")]
end

subgraph group_retrieval["Query and retrieval"]
  node_query_flow["Query workflow<br/>[search_index.py]"]
  node_query_parser["Constraint parser<br/>[search_index.py]"]
  node_rule_filter["Rule filter<br/>[search_index.py]"]
  node_fallback["Fallback candidates<br/>[search_index.py]"]
end

subgraph group_answer["Ranking and answer"]
  node_reranker["ColBERT reranker<br/>[rag_common.py]"]
  node_context_builder["Answer context<br/>[search_index.py]"]
  node_llm["DashScope Qwen"]
  node_result["Answer and product details<br/>[search_index.py]"]
end

node_user(("User"))

node_product_docs -->|"reads Markdown"| node_index_builder
node_index_builder -->|"creates embeddings"| node_embedding
node_index_builder -->|"writes index"| node_faiss
node_user -->|"submits query"| node_query_flow
node_query_flow -->|"parses constraints"| node_query_parser
node_query_flow -->|"creates embeddings"| node_embedding
node_query_flow -->|"loads and searches"| node_faiss
node_query_flow -->|"filters candidates"| node_rule_filter
node_query_flow -->|"selects Top 8"| node_fallback
node_query_flow -->|"reranks candidates"| node_reranker
node_query_flow -->|"builds prompt context"| node_context_builder
node_query_flow -->|"invokes model"| node_llm
node_context_builder -->|"supplies prompt"| node_llm
node_query_flow -->|"prints answer and details"| node_result

click node_product_docs "https://github.com/522blackcat/appleproductrag/tree/main/docs"
click node_index_builder "https://github.com/522blackcat/appleproductrag/blob/main/build_index.py"
click node_embedding "https://github.com/522blackcat/appleproductrag/blob/main/rag_common.py"
click node_faiss "https://github.com/522blackcat/appleproductrag/tree/main/faiss_index"
click node_query_flow "https://github.com/522blackcat/appleproductrag/blob/main/search_index.py"
click node_query_parser "https://github.com/522blackcat/appleproductrag/blob/main/search_index.py"
click node_rule_filter "https://github.com/522blackcat/appleproductrag/blob/main/search_index.py"
click node_fallback "https://github.com/522blackcat/appleproductrag/blob/main/search_index.py"
click node_reranker "https://github.com/522blackcat/appleproductrag/blob/main/rag_common.py"
click node_context_builder "https://github.com/522blackcat/appleproductrag/blob/main/search_index.py"
click node_result "https://github.com/522blackcat/appleproductrag/blob/main/search_index.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_product_docs,node_index_builder,node_embedding,node_faiss,node_user toneBlue
class node_query_flow,node_query_parser,node_rule_filter,node_fallback toneAmber
class node_reranker,node_context_builder,node_llm,node_result toneMint
```

## Components

### Product corpus and index

- [Product documents](https://github.com/522blackcat/appleproductrag/tree/main/docs): `docs`
- [Index builder](https://github.com/522blackcat/appleproductrag/blob/main/build_index.py): `build_index.py`
- [Embedding model](https://github.com/522blackcat/appleproductrag/blob/main/rag_common.py): `rag_common.py`
- [FAISS index](https://github.com/522blackcat/appleproductrag/tree/main/faiss_index): `faiss_index`

### Query and retrieval

- [Query workflow](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py): `search_index.py`
- [Constraint parser](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py): `search_index.py`
- [Rule filter](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py): `search_index.py`
- [Fallback candidates](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py): `search_index.py`

### Ranking and answer

- [ColBERT reranker](https://github.com/522blackcat/appleproductrag/blob/main/rag_common.py): `rag_common.py`
- [Answer context](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py): `search_index.py`
- **DashScope Qwen**
- [Answer and product details](https://github.com/522blackcat/appleproductrag/blob/main/search_index.py): `search_index.py`

### Other components

- **User**

## Connections

- Product documents → Index builder: reads Markdown (evidence: `build_index.py`)
- Index builder → Embedding model: creates embeddings (evidence: `build_index.py`)
- Index builder → FAISS index: writes index (evidence: `build_index.py`)
- User → Query workflow: submits query (evidence: `README.md`)
- Query workflow → Constraint parser: parses constraints (evidence: `search_index.py`)
- Query workflow → Embedding model: creates embeddings (evidence: `search_index.py`)
- Query workflow → FAISS index: loads and searches (evidence: `search_index.py`)
- Query workflow → Rule filter: filters candidates (evidence: `search_index.py`)
- Query workflow → Fallback candidates: selects Top 8 (evidence: `README.md`)
- Query workflow → ColBERT reranker: reranks candidates (evidence: `search_index.py`)
- Query workflow → Answer context: builds prompt context (evidence: `search_index.py`)
- Query workflow → DashScope Qwen: invokes model (evidence: `search_index.py`)
- Answer context → DashScope Qwen: supplies prompt (evidence: `search_index.py`)
- Query workflow → Answer and product details: prints answer and details (evidence: `search_index.py`)
