# ai-mentorship/debate-match-rag architecture

> Architecture diagram of the GitHub repository ai-mentorship/debate-match-rag, 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/ai-mentorship/debate-match-rag
- Repository: https://github.com/ai-mentorship/debate-match-rag

## Overview

DebateMatch is an AI-assisted debate transcript explorer and question-answering system. Its principal workflow is a user submitting a question to the backend, which retrieves relevant debate passages and returns a grounded answer; a separate claim-checking route evaluates claims against external evidence. Transcript ingestion and indexing support these features, while the React frontend also provides transcript browsing and informational pages. The excerpts establish the backend’s retrieval and fact-checking calls, but do not show frontend-to-backend request wiring or the full ingestion/indexing call sequence, so those relationships are omitted or marked unverified.

Main entry points: [`src/main.py`](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/main.py) (Flask application), [`src/frontend/src/App.jsx`](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/App.jsx) (Page router), [`src/backend/retriever/retriever.py`](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/retriever/retriever.py) (Passage retrieval), [`src/backend/fact_checker_prototype/AI_FactChecker.py`](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/fact_checker_prototype/AI_FactChecker.py) (Claim fact checker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["Page router<br/>[App.jsx]"]
  node_analyzer["Analyzer<br/>[Analyzer.jsx]"]
  node_transcripts["Transcript browser<br/>[Transcripts.jsx]"]
  node_home["Home page<br/>[Home.jsx]"]
  node_missions["Mission page<br/>[Missions.jsx]"]
  node_team["Team page<br/>[Team.jsx]"]
  node_header["Navigation header<br/>[Header.jsx]"]
end

subgraph group_backend["Backend routes"]
  node_api["Flask application<br/>[main.py]"]
end

subgraph group_ingestion["Transcript ingestion"]
  node_preprocess["Transcript cleaner"]
  node_database[("MongoDB collections<br/>[connection.py]")]
  node_inserter["Transcript loader<br/>[insert.py]"]
  node_faiss_build["FAISS index builder<br/>[build_index.py]"]
  node_faiss_increment["Incremental indexing"]
end

subgraph group_intelligence["Retrieval and analysis"]
  node_retriever["Passage retrieval<br/>[retriever.py]"]
  node_qa["RAG answer pipeline<br/>[QA_pipeline.py]"]
  node_fact_checker["Claim fact checker<br/>[AI_FactChecker.py]"]
  node_llm_client["GPT client<br/>[gpt5_nano.py]"]
end

node_user(("User"))
node_openai{{"OpenAI services"}}
node_wikipedia{{"Wikipedia API"}}
node_news_api{{"News API"}}

node_user -->|"uses"| node_app
node_app -->|"renders"| node_header
node_app -->|"routes"| node_home
node_app -->|"routes"| node_analyzer
node_app -->|"routes"| node_transcripts
node_app -->|"routes"| node_missions
node_app -->|"routes"| node_team
node_transcripts -->|"shows transcripts"| node_user
node_analyzer -.->|"submits queries"| node_api
node_api -->|"retrieves passages"| node_retriever
node_api -->|"checks claims"| node_fact_checker
node_api -.->|"generates answers"| node_qa
node_api -.->|"processes uploads"| node_preprocess
node_api -.->|"loads transcripts"| node_inserter
node_api -.->|"builds index"| node_faiss_build
node_api -->|"updates index"| node_faiss_increment
node_inserter -->|"writes records"| node_database
node_database -->|"connects through"| node_inserter
node_retriever -->|"embeds queries"| node_openai
node_retriever -.->|"searches index"| node_faiss_build
node_qa -->|"embeds and generates"| node_openai
node_api -.->|"uses client"| node_llm_client
node_fact_checker -->|"searches evidence"| node_wikipedia
node_fact_checker -.->|"searches evidence"| node_news_api

click node_app "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/App.jsx"
click node_analyzer "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Analyzer.jsx"
click node_transcripts "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Transcripts.jsx"
click node_home "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Home.jsx"
click node_missions "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Missions.jsx"
click node_team "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Team.jsx"
click node_header "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/components/Header.jsx"
click node_api "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/main.py"
click node_preprocess "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/preprocessing/preprocess_script.py"
click node_database "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/database/connection.py"
click node_inserter "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/database/insert.py"
click node_faiss_build "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/embeddings_faiss/build_index.py"
click node_faiss_increment "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/embeddings_faiss/incremental_index.py"
click node_retriever "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/retriever/retriever.py"
click node_qa "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/qa_pipeline/QA_pipeline.py"
click node_fact_checker "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/fact_checker_prototype/AI_FactChecker.py"
click node_llm_client "https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/core_llm/gpt5_nano.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_app,node_analyzer,node_transcripts,node_home,node_missions,node_team,node_header,node_user toneBlue
class node_api toneAmber
class node_preprocess,node_database,node_inserter,node_faiss_build,node_faiss_increment,node_wikipedia,node_news_api toneMint
class node_retriever,node_qa,node_fact_checker,node_llm_client toneRose
class node_openai toneIndigo
```

## Components

### User interface

- [Page router](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/App.jsx): `src/frontend/src/App.jsx`
- [Analyzer](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Analyzer.jsx): `src/frontend/src/pages/Analyzer.jsx`
- [Transcript browser](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Transcripts.jsx): `src/frontend/src/pages/Transcripts.jsx`
- [Home page](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Home.jsx): `src/frontend/src/pages/Home.jsx`
- [Mission page](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Missions.jsx): `src/frontend/src/pages/Missions.jsx`
- [Team page](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/pages/Team.jsx): `src/frontend/src/pages/Team.jsx`
- [Navigation header](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/frontend/src/components/Header.jsx): `src/frontend/src/components/Header.jsx`

### Backend routes

- [Flask application](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/main.py): `src/main.py`

### Transcript ingestion

- [Transcript cleaner](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/preprocessing/preprocess_script.py): `src/backend/preprocessing/preprocess_script.py`
- [MongoDB collections](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/database/connection.py): `src/backend/database/connection.py`
- [Transcript loader](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/database/insert.py): `src/backend/database/insert.py`
- [FAISS index builder](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/embeddings_faiss/build_index.py): `src/backend/embeddings_faiss/build_index.py`
- [Incremental indexing](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/embeddings_faiss/incremental_index.py): `src/backend/embeddings_faiss/incremental_index.py`

### Retrieval and analysis

- [Passage retrieval](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/retriever/retriever.py): `src/backend/retriever/retriever.py`
- [RAG answer pipeline](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/qa_pipeline/QA_pipeline.py): `src/backend/qa_pipeline/QA_pipeline.py`
- [Claim fact checker](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/fact_checker_prototype/AI_FactChecker.py): `src/backend/fact_checker_prototype/AI_FactChecker.py`
- [GPT client](https://github.com/ai-mentorship/debate-match-rag/blob/main/src/backend/core_llm/gpt5_nano.py): `src/backend/core_llm/gpt5_nano.py`

### Other components

- **User**
- **OpenAI services**
- **Wikipedia API**
- **News API**

## Connections

- User → Page router: uses
- Page router → Navigation header: renders (evidence: `src/frontend/src/App.jsx`)
- Page router → Home page: routes (evidence: `src/frontend/src/App.jsx`)
- Page router → Analyzer: routes (evidence: `src/frontend/src/App.jsx`)
- Page router → Transcript browser: routes (evidence: `src/frontend/src/App.jsx`)
- Page router → Mission page: routes (evidence: `src/frontend/src/App.jsx`)
- Page router → Team page: routes (evidence: `src/frontend/src/App.jsx`)
- Transcript browser → User: shows transcripts (evidence: `src/frontend/src/pages/Transcripts.jsx`)
- Analyzer → Flask application: submits queries
- Flask application → Passage retrieval: retrieves passages (evidence: `src/main.py`)
- Flask application → Claim fact checker: checks claims (evidence: `src/main.py`)
- Flask application → RAG answer pipeline: generates answers (evidence: `src/main.py`)
- Flask application → Transcript cleaner: processes uploads (evidence: `src/main.py`)
- Flask application → Transcript loader: loads transcripts (evidence: `src/main.py`)
- Flask application → FAISS index builder: builds index (evidence: `src/main.py`)
- Flask application → Incremental indexing: updates index (evidence: `src/main.py`)
- Transcript loader → MongoDB collections: writes records (evidence: `src/backend/database/insert.py`)
- MongoDB collections → Transcript loader: connects through (evidence: `src/backend/database/insert.py`)
- Passage retrieval → OpenAI services: embeds queries (evidence: `src/backend/retriever/retriever.py`)
- Passage retrieval → FAISS index builder: searches index
- RAG answer pipeline → OpenAI services: embeds and generates (evidence: `src/backend/qa_pipeline/QA_pipeline.py`)
- Flask application → GPT client: uses client (evidence: `src/main.py`)
- Claim fact checker → Wikipedia API: searches evidence (evidence: `src/backend/fact_checker_prototype/AI_FactChecker.py`)
- Claim fact checker → News API: searches evidence