# adityardy05/truthlensai architecture

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

- Interactive diagram: https://gitdiagram.com/adityardy05/truthlensai
- Repository: https://github.com/adityardy05/truthlensai

## Overview

TruthLens verifies claims submitted as text, images, or URLs, returning a verdict with confidence, justification, recommendations, and supporting evidence. The web app and Telegram bot are separate entry points; the backend service normalizes inputs, retrieves evidence, and runs the Team B judgment graph. Retrieval combines live web results with historical indexed records and ranks evidence using relevance, domain credibility, and recency. The README describes the LIAR dataset rather than this application; sampled excerpts do not expose API route internals or the full judgment graph wiring, so those links are kept conservative.

Main entry points: [`backend/agents/team_b/graph.py`](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/graph.py) (Judgment graph), [`backend/services/verification_service.py`](https://github.com/adityardy05/truthlensai/blob/rag/backend/services/verification_service.py) (Verification service), [`backend/rag/retriever.py`](https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/retriever.py) (Retrieval pipeline), [`backend/rag/web_retriever.py`](https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/web_retriever.py) (Web search and scraping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_web_ui["Web interface<br/>[app.js]"]
  node_web_api_client["Web API client<br/>[api.js]"]
  node_telegram["Telegram bot<br/>[main.py]"]
  node_telegram_handlers["Bot handlers<br/>[handlers.py]"]
  node_bot_client["Backend client<br/>[backend_client.py]"]
end

subgraph group_backend["Verification backend"]
  node_flask_app["Flask application<br/>[app.py]"]
  node_verification_api["Verification API<br/>[verification.py]"]
  node_verification_service["Verification service"]
  node_url_extraction["Article extraction<br/>[url_extraction.py]"]
  node_image_preprocessing["OCR and language<br/>[image_ocr.py]"]
end

subgraph group_evidence["Evidence retrieval"]
  node_retrieval_pipeline["Retrieval pipeline<br/>[retriever.py]"]
  node_web_search["Web search and scraping<br/>[web_retriever.py]"]
  node_historical_index[("Historical claim index<br/>[retriever.py]")]
  node_domain_credibility["Domain credibility"]
end

subgraph group_judgment["Claim judgment"]
  node_team_graph["Judgment graph<br/>[graph.py]"]
  node_claim_decomposition["Claim decomposition<br/>[decompose_claim.py]"]
  node_qa_rounds["Evidence QA rounds<br/>[round1_qa.py]"]
  node_credibility_check["Credibility check"]
  node_confidence_gate["Confidence gate<br/>[confidence_gate.py]"]
  node_final_judgment["Final judgment<br/>[final_judgment.py]"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
end

node_user(("Claim submitter"))
node_tavily["Tavily search"]
node_article_sites["Article websites"]
node_ollama["Ollama model service"]

node_user -->|"submits claim"| node_web_ui
node_web_ui -->|"requests verification"| node_web_api_client
node_user -->|"sends text or photo"| node_telegram
node_telegram -->|"dispatches message"| node_telegram_handlers
node_telegram_handlers -->|"sends verification"| node_bot_client
node_bot_client -->|"posts claim or image"| node_verification_api
node_flask_app -->|"registers routes"| node_verification_api
node_flask_app -->|"creates service"| node_verification_service
node_verification_service -->|"extracts article text"| node_url_extraction
node_verification_service -->|"processes image or language"| node_image_preprocessing
node_verification_service -->|"retrieves evidence"| node_retrieval_pipeline
node_verification_service -->|"runs judgment graph"| node_team_graph
node_retrieval_pipeline -->|"searches live web"| node_web_search
node_web_search -->|"queries"| node_tavily
node_web_search -->|"scrapes articles"| node_article_sites
node_retrieval_pipeline -->|"searches records"| node_historical_index
node_retrieval_pipeline -->|"scores source domains"| node_domain_credibility
node_team_graph -->|"dispatches stage"| node_claim_decomposition
node_team_graph -->|"dispatches QA"| node_qa_rounds
node_team_graph -->|"dispatches check"| node_credibility_check
node_team_graph -->|"dispatches gate"| node_confidence_gate
node_team_graph -->|"dispatches verdict"| node_final_judgment
node_llm_client -->|"requests generation"| node_ollama

click node_web_ui "https://github.com/adityardy05/truthlensai/blob/rag/frontend/js/app.js"
click node_web_api_client "https://github.com/adityardy05/truthlensai/blob/rag/frontend/js/api.js"
click node_telegram "https://github.com/adityardy05/truthlensai/blob/rag/bot/main.py"
click node_telegram_handlers "https://github.com/adityardy05/truthlensai/blob/rag/bot/handlers.py"
click node_bot_client "https://github.com/adityardy05/truthlensai/blob/rag/bot/backend_client.py"
click node_flask_app "https://github.com/adityardy05/truthlensai/blob/rag/backend/app.py"
click node_verification_api "https://github.com/adityardy05/truthlensai/blob/rag/backend/api/verification.py"
click node_verification_service "https://github.com/adityardy05/truthlensai/blob/rag/backend/services/verification_service.py"
click node_url_extraction "https://github.com/adityardy05/truthlensai/blob/rag/backend/services/url_extraction.py"
click node_image_preprocessing "https://github.com/adityardy05/truthlensai/blob/rag/backend/preprocessing/image_ocr.py"
click node_retrieval_pipeline "https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/retriever.py"
click node_web_search "https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/web_retriever.py"
click node_historical_index "https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/retriever.py"
click node_domain_credibility "https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/domain_credibility.py"
click node_team_graph "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/graph.py"
click node_claim_decomposition "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/decompose_claim.py"
click node_qa_rounds "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/round1_qa.py"
click node_credibility_check "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/credibility_check.py"
click node_confidence_gate "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/confidence_gate.py"
click node_final_judgment "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/final_judgment.py"
click node_llm_client "https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/llm_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_web_ui,node_web_api_client,node_telegram,node_telegram_handlers,node_bot_client toneBlue
class node_flask_app,node_verification_api,node_verification_service,node_url_extraction,node_image_preprocessing toneAmber
class node_retrieval_pipeline,node_web_search,node_historical_index,node_domain_credibility toneMint
class node_team_graph,node_claim_decomposition,node_qa_rounds,node_credibility_check,node_confidence_gate,node_final_judgment,node_llm_client toneRose
class node_user,node_tavily,node_article_sites,node_ollama toneIndigo
```

## Components

### User entry points

- [Web interface](https://github.com/adityardy05/truthlensai/blob/rag/frontend/js/app.js): `frontend/js/app.js`
- [Web API client](https://github.com/adityardy05/truthlensai/blob/rag/frontend/js/api.js): `frontend/js/api.js`
- [Telegram bot](https://github.com/adityardy05/truthlensai/blob/rag/bot/main.py): `bot/main.py`
- [Bot handlers](https://github.com/adityardy05/truthlensai/blob/rag/bot/handlers.py): `bot/handlers.py`
- [Backend client](https://github.com/adityardy05/truthlensai/blob/rag/bot/backend_client.py): `bot/backend_client.py`

### Verification backend

- [Flask application](https://github.com/adityardy05/truthlensai/blob/rag/backend/app.py): `backend/app.py`
- [Verification API](https://github.com/adityardy05/truthlensai/blob/rag/backend/api/verification.py): `backend/api/verification.py`
- [Verification service](https://github.com/adityardy05/truthlensai/blob/rag/backend/services/verification_service.py): `backend/services/verification_service.py`
- [Article extraction](https://github.com/adityardy05/truthlensai/blob/rag/backend/services/url_extraction.py): `backend/services/url_extraction.py`
- [OCR and language](https://github.com/adityardy05/truthlensai/blob/rag/backend/preprocessing/image_ocr.py): `backend/preprocessing/image_ocr.py`

### Evidence retrieval

- [Retrieval pipeline](https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Web search and scraping](https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/web_retriever.py): `backend/rag/web_retriever.py`
- [Historical claim index](https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/retriever.py): `backend/rag/retriever.py`
- [Domain credibility](https://github.com/adityardy05/truthlensai/blob/rag/backend/rag/domain_credibility.py): `backend/rag/domain_credibility.py`

### Claim judgment

- [Judgment graph](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/graph.py): `backend/agents/team_b/graph.py`
- [Claim decomposition](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/decompose_claim.py): `backend/agents/team_b/nodes/decompose_claim.py`
- [Evidence QA rounds](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/round1_qa.py): `backend/agents/team_b/nodes/round1_qa.py`
- [Credibility check](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/credibility_check.py): `backend/agents/team_b/nodes/credibility_check.py`
- [Confidence gate](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/confidence_gate.py): `backend/agents/team_b/nodes/confidence_gate.py`
- [Final judgment](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/team_b/nodes/final_judgment.py): `backend/agents/team_b/nodes/final_judgment.py`
- [LLM client](https://github.com/adityardy05/truthlensai/blob/rag/backend/agents/llm_client.py): `backend/agents/llm_client.py`

### Other components

- **Claim submitter**
- **Tavily search**
- **Article websites**
- **Ollama model service**

## Connections

- Claim submitter → Web interface: submits claim
- Web interface → Web API client: requests verification
- Claim submitter → Telegram bot: sends text or photo
- Telegram bot → Bot handlers: dispatches message
- Bot handlers → Backend client: sends verification
- Backend client → Verification API: posts claim or image
- Flask application → Verification API: registers routes
- Flask application → Verification service: creates service
- Verification service → Article extraction: extracts article text
- Verification service → OCR and language: processes image or language
- Verification service → Retrieval pipeline: retrieves evidence
- Verification service → Judgment graph: runs judgment graph
- Retrieval pipeline → Web search and scraping: searches live web
- Web search and scraping → Tavily search: queries
- Web search and scraping → Article websites: scrapes articles
- Retrieval pipeline → Historical claim index: searches records
- Retrieval pipeline → Domain credibility: scores source domains
- Judgment graph → Claim decomposition: dispatches stage
- Judgment graph → Evidence QA rounds: dispatches QA
- Judgment graph → Credibility check: dispatches check
- Judgment graph → Confidence gate: dispatches gate
- Judgment graph → Final judgment: dispatches verdict
- LLM client → Ollama model service: requests generation