# aerex0/recor-rag architecture

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

- Interactive diagram: https://gitdiagram.com/aerex0/recor-rag
- Repository: https://github.com/aerex0/recor-rag

## Overview

ReCOR RAG is a transcript-oriented conversational analytics project: it develops query datasets, runs retrieval-augmented answer generation, and presents answers with transcript evidence. The principal user workflow is to submit a curated dataset query through the web interface, run the answer-generation notebook against the RAG assets and model server, and inspect the answer and evidence. The README documents three query-generation approaches and evaluation; sampled code gives more detail for method 2 and the web chat state. Several notebook and backend relationships are documented only at a high level, so those links are kept broad.

Main entry points: [`queries-generation/method-2/main.py`](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/main.py) (Pipeline orchestration), [`queries-generation/method-2/auto_evol.py`](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/auto_evol.py) (Query evolution), [`recor-rag/answer-generation.ipynb`](https://github.com/aerex0/recor-rag/blob/main/recor-rag/answer-generation.ipynb) (Answer generation), [`queries-generation/method-2/self_instruct.py`](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/self_instruct.py) (Self-Instruct)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query_creation["Query creation"]
  node_method1_generate["Taxonomy generation"]
  node_method1_evaluate["Query evaluation"]
  node_seed_generation["Seed generation<br/>[seed_generator.py]"]
  node_method2_orchestrator["Pipeline orchestration<br/>[main.py]"]
  node_self_instruct["Self-Instruct<br/>[self_instruct.py]"]
  node_auto_evol["Query evolution<br/>[auto_evol.py]"]
  node_failure_detection["Evolution checks"]
  node_prompt_templates["Prompt templates<br/>[prompts.py]"]
  node_pipeline_config["Pipeline settings<br/>[config.py]"]
  node_groq_client["Groq client<br/>[llm_client.py]"]
  node_method3_generation["Transcript-based generation"]
end

subgraph group_rag_runtime["RAG runtime"]
  node_answer_notebook["Answer generation"]
  node_rag_index[("FAISS index")]
  node_transcript_summaries["Transcript summaries<br/>[summaries-20k.json]"]
  node_vllm_server["vLLM model server"]
  node_answer_evidence["Answer and evidence"]
end

subgraph group_web_app["Web app"]
  node_web_chat["Chat interface<br/>[page.tsx]"]
  node_chat_state["Chat state<br/>[useChatStore.ts]"]
  node_chat_api["Chat API route<br/>[route.ts]"]
end

subgraph group_data_assets["Data assets"]
  node_curated_queries["Curated queries"]
end

node_analyst(("Analyst"))

node_analyst -->|"submits query"| node_web_chat
node_web_chat -->|"uses chat state"| node_chat_state
node_curated_queries -->|"provides test queries"| node_answer_notebook
node_answer_notebook -->|"produces answer"| node_answer_evidence
node_answer_notebook -->|"uses retrieval index"| node_rag_index
node_answer_notebook -.->|"uses summaries"| node_transcript_summaries
node_answer_notebook -->|"queries model"| node_vllm_server
node_method2_orchestrator -->|"runs stage one"| node_self_instruct
node_method2_orchestrator -->|"runs stage two"| node_auto_evol
node_method2_orchestrator -->|"creates clients"| node_groq_client
node_method2_orchestrator -->|"gets output paths"| node_pipeline_config
node_self_instruct -->|"requests completions"| node_groq_client
node_self_instruct -->|"uses prompts"| node_prompt_templates
node_self_instruct -->|"uses settings"| node_pipeline_config
node_auto_evol -->|"requests completions"| node_groq_client
node_auto_evol -->|"checks evolutions"| node_failure_detection
node_auto_evol -->|"uses prompts"| node_prompt_templates
node_auto_evol -->|"uses settings"| node_pipeline_config
node_seed_generation -->|"requests completions"| node_groq_client
node_method1_generate -.->|"queries evaluated"| node_method1_evaluate
node_method1_generate -.->|"contributes queries"| node_curated_queries
node_method3_generation -.->|"contributes queries"| node_curated_queries
node_method2_orchestrator -.->|"generates query data"| node_curated_queries

click node_web_chat "https://github.com/aerex0/recor-rag/blob/main/website/app/page.tsx"
click node_chat_state "https://github.com/aerex0/recor-rag/blob/main/website/app/stores/useChatStore.ts"
click node_chat_api "https://github.com/aerex0/recor-rag/blob/main/website/app/api/chat/route.ts"
click node_method1_generate "https://github.com/aerex0/recor-rag/tree/main/queries-generation/method-1/query-generation"
click node_method1_evaluate "https://github.com/aerex0/recor-rag/tree/main/queries-generation/method-1/query-evaluation"
click node_seed_generation "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/seed_generator.py"
click node_method2_orchestrator "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/main.py"
click node_self_instruct "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/self_instruct.py"
click node_auto_evol "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/auto_evol.py"
click node_failure_detection "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/utils/failure_detector.py"
click node_prompt_templates "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/utils/prompts.py"
click node_pipeline_config "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/config.py"
click node_groq_client "https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/utils/llm_client.py"
click node_method3_generation "https://github.com/aerex0/recor-rag/tree/main/queries-generation/method-3"
click node_curated_queries "https://github.com/aerex0/recor-rag/tree/main/simulated-real-query-system"
click node_answer_notebook "https://github.com/aerex0/recor-rag/blob/main/recor-rag/answer-generation.ipynb"
click node_rag_index "https://github.com/aerex0/recor-rag/tree/main/recor-rag/const/faiss_index"
click node_transcript_summaries "https://github.com/aerex0/recor-rag/blob/main/recor-rag/const/summaries-20k.json"
click node_answer_evidence "https://github.com/aerex0/recor-rag/blob/main/recor-rag/answer-generation.ipynb"

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_method1_generate,node_method1_evaluate,node_seed_generation,node_method2_orchestrator,node_self_instruct,node_auto_evol,node_failure_detection,node_prompt_templates,node_pipeline_config,node_groq_client,node_method3_generation toneBlue
class node_answer_notebook,node_rag_index,node_transcript_summaries,node_vllm_server,node_answer_evidence toneAmber
class node_web_chat,node_chat_state,node_chat_api toneMint
class node_curated_queries toneRose
class node_analyst toneIndigo
```

## Components

### Query creation

- [Taxonomy generation](https://github.com/aerex0/recor-rag/tree/main/queries-generation/method-1/query-generation): `queries-generation/method-1/query-generation`
- [Query evaluation](https://github.com/aerex0/recor-rag/tree/main/queries-generation/method-1/query-evaluation): `queries-generation/method-1/query-evaluation`
- [Seed generation](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/seed_generator.py): `queries-generation/method-2/seed_generator.py`
- [Pipeline orchestration](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/main.py): `queries-generation/method-2/main.py`
- [Self-Instruct](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/self_instruct.py): `queries-generation/method-2/self_instruct.py`
- [Query evolution](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/auto_evol.py): `queries-generation/method-2/auto_evol.py`
- [Evolution checks](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/utils/failure_detector.py): `queries-generation/method-2/utils/failure_detector.py`
- [Prompt templates](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/utils/prompts.py): `queries-generation/method-2/utils/prompts.py`
- [Pipeline settings](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/config.py): `queries-generation/method-2/config.py`
- [Groq client](https://github.com/aerex0/recor-rag/blob/main/queries-generation/method-2/utils/llm_client.py): `queries-generation/method-2/utils/llm_client.py`
- [Transcript-based generation](https://github.com/aerex0/recor-rag/tree/main/queries-generation/method-3): `queries-generation/method-3`

### RAG runtime

- [Answer generation](https://github.com/aerex0/recor-rag/blob/main/recor-rag/answer-generation.ipynb): `recor-rag/answer-generation.ipynb`
- [FAISS index](https://github.com/aerex0/recor-rag/tree/main/recor-rag/const/faiss_index): `recor-rag/const/faiss_index`
- [Transcript summaries](https://github.com/aerex0/recor-rag/blob/main/recor-rag/const/summaries-20k.json): `recor-rag/const/summaries-20k.json`
- **vLLM model server**
- [Answer and evidence](https://github.com/aerex0/recor-rag/blob/main/recor-rag/answer-generation.ipynb): `recor-rag/answer-generation.ipynb`

### Web app

- [Chat interface](https://github.com/aerex0/recor-rag/blob/main/website/app/page.tsx): `website/app/page.tsx`
- [Chat state](https://github.com/aerex0/recor-rag/blob/main/website/app/stores/useChatStore.ts): `website/app/stores/useChatStore.ts`
- [Chat API route](https://github.com/aerex0/recor-rag/blob/main/website/app/api/chat/route.ts): `website/app/api/chat/route.ts`

### Data assets

- [Curated queries](https://github.com/aerex0/recor-rag/tree/main/simulated-real-query-system): `simulated-real-query-system`

### Other components

- **Analyst**

## Connections

- Analyst → Chat interface: submits query (evidence: `README.md`)
- Chat interface → Chat state: uses chat state (evidence: `website/app/page.tsx`)
- Curated queries → Answer generation: provides test queries (evidence: `README.md`)
- Answer generation → Answer and evidence: produces answer (evidence: `README.md`)
- Answer generation → FAISS index: uses retrieval index (evidence: `README.md`)
- Answer generation → Transcript summaries: uses summaries
- Answer generation → vLLM model server: queries model (evidence: `README.md`)
- Pipeline orchestration → Self-Instruct: runs stage one (evidence: `queries-generation/method-2/main.py`)
- Pipeline orchestration → Query evolution: runs stage two (evidence: `queries-generation/method-2/main.py`)
- Pipeline orchestration → Groq client: creates clients (evidence: `queries-generation/method-2/main.py`)
- Pipeline orchestration → Pipeline settings: gets output paths (evidence: `queries-generation/method-2/main.py`)
- Self-Instruct → Groq client: requests completions (evidence: `queries-generation/method-2/self_instruct.py`)
- Self-Instruct → Prompt templates: uses prompts (evidence: `queries-generation/method-2/self_instruct.py`)
- Self-Instruct → Pipeline settings: uses settings (evidence: `queries-generation/method-2/self_instruct.py`)
- Query evolution → Groq client: requests completions (evidence: `queries-generation/method-2/auto_evol.py`)
- Query evolution → Evolution checks: checks evolutions (evidence: `queries-generation/method-2/auto_evol.py`)
- Query evolution → Prompt templates: uses prompts (evidence: `queries-generation/method-2/auto_evol.py`)
- Query evolution → Pipeline settings: uses settings (evidence: `queries-generation/method-2/auto_evol.py`)
- Seed generation → Groq client: requests completions (evidence: `queries-generation/method-2/seed_generator.py`)
- Taxonomy generation → Query evaluation: queries evaluated
- Taxonomy generation → Curated queries: contributes queries
- Transcript-based generation → Curated queries: contributes queries
- Pipeline orchestration → Curated queries: generates query data
