# giharanavindu/truthbomb architecture

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

- Interactive diagram: https://gitdiagram.com/giharanavindu/truthbomb
- Repository: https://github.com/giharanavindu/truthbomb

## Overview

TruthBomb is a multilingual, local-first social-media fact-checking application. A user submits a post in the React interface; the FastAPI boundary runs a LangGraph workflow that extracts a normalized claim, retrieves local evidence, routes research locally or to trusted web search, adjudicates findings, and translates the result. The interface presents the verdict, sources, and a live-news ticker. Separate ingestion workers keep the local OSINT corpus current. The graph reflects documented calls and README capabilities; some unsampled internals and the precise connection of synthesis to the runtime are not established by the excerpts.

Main entry points: [`src/pipeline.py`](https://github.com/giharanavindu/truthbomb/blob/dev/src/pipeline.py) (State workflow), [`frontend/src/App.tsx`](https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/App.tsx) (Application UI), [`src/agents/web_researcher.py`](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/web_researcher.py) (Web research), [`src/main.py`](https://github.com/giharanavindu/truthbomb/blob/dev/src/main.py) (FastAPI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User Interface"]
  node_app["Application UI<br/>[App.tsx]"]
  node_form["Claim form"]
  node_ticker["News ticker"]
  node_result["Verdict card<br/>[ResultCard.tsx]"]
  node_sources["Context sources<br/>[ContextSources.tsx]"]
end

subgraph group_api["API and Workflow"]
  node_api["FastAPI service<br/>[main.py]"]
  node_workflow["State workflow<br/>[pipeline.py]"]
  node_state["Agent state<br/>[state.py]"]
end

subgraph group_research["Research and Verification"]
  node_extractor_agent["Claim extraction<br/>[claim_extractor.py]"]
  node_retrieval_agent["Retrieval node<br/>[retriever.py]"]
  node_local_research["Local research"]
  node_web_research["Web research<br/>[web_researcher.py]"]
  node_adjudicator["Adjudication<br/>[adjudicator.py]"]
  node_synthesis["Verdict synthesis<br/>[synthesis.py]"]
  node_translator["Translation<br/>[translator.py]"]
end

subgraph group_evidence["Evidence and Ingestion"]
  node_hybrid_tool["Hybrid retrieval"]
  node_rag_retriever["RAG retriever<br/>[retriever.py]"]
  node_fusion["Rank fusion<br/>[fusion.py]"]
  node_local_tool["Local DB verifier<br/>[local_db_tool.py]"]
  node_vector_store[("Chroma store<br/>[local_db_tool.py]")]
  node_web_tool["Trusted web search<br/>[web_search_tool.py]"]
end

subgraph group_language["Language Models"]
  node_extractor_model["GGUF extractor<br/>[extractor.py]"]
end

node_user(("Fact-check user"))
node_news_sources(("Telegram and RSS"))
node_gemini["Gemini service"]

node_user -->|"enters claim"| node_form
node_form -->|"submits text"| node_app
node_app -->|"posts verification"| node_api
node_api -->|"runs graph"| node_workflow
node_workflow -->|"starts extraction"| node_extractor_agent
node_workflow -->|"dispatches retrieval"| node_retrieval_agent
node_workflow -->|"routes locally"| node_local_research
node_workflow -->|"routes to web"| node_web_research
node_workflow -->|"dispatches findings"| node_adjudicator
node_workflow -->|"translates verdict"| node_translator
node_extractor_agent -->|"extracts claim"| node_extractor_model
node_retrieval_agent -->|"retrieves evidence"| node_hybrid_tool
node_local_research -->|"verifies locally"| node_local_tool
node_local_research -->|"falls back"| node_web_research
node_web_research -->|"searches web"| node_web_tool
node_hybrid_tool -->|"queries dense store"| node_vector_store
node_hybrid_tool -.->|"uses retrieval"| node_rag_retriever
node_rag_retriever -->|"fuses rankings"| node_fusion
node_local_tool -->|"retrieves context"| node_rag_retriever
node_local_tool -->|"reads documents"| node_vector_store
node_news_sources -->|"feeds corpus"| node_vector_store
node_extractor_model -->|"uses fallback"| node_gemini
node_web_research -->|"requests verdict"| node_gemini
node_app -->|"renders ticker"| node_ticker
node_app -->|"renders verdict"| node_result
node_app -->|"renders sources"| node_sources
node_api -.->|"returns response"| node_app
node_adjudicator -.->|"may synthesize"| node_synthesis

click node_app "https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/App.tsx"
click node_form "https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/FactCheckerForm.tsx"
click node_ticker "https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/LatestNewsTicker.tsx"
click node_result "https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/ResultCard.tsx"
click node_sources "https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/ContextSources.tsx"
click node_api "https://github.com/giharanavindu/truthbomb/blob/dev/src/main.py"
click node_workflow "https://github.com/giharanavindu/truthbomb/blob/dev/src/pipeline.py"
click node_state "https://github.com/giharanavindu/truthbomb/blob/dev/src/state.py"
click node_extractor_agent "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/claim_extractor.py"
click node_retrieval_agent "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/retriever.py"
click node_local_research "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/local_researcher.py"
click node_web_research "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/web_researcher.py"
click node_adjudicator "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/adjudicator.py"
click node_synthesis "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/synthesis.py"
click node_translator "https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/translator.py"
click node_hybrid_tool "https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/hybrid_retriever.py"
click node_rag_retriever "https://github.com/giharanavindu/truthbomb/blob/dev/src/rag/retriever.py"
click node_fusion "https://github.com/giharanavindu/truthbomb/blob/dev/src/rag/fusion.py"
click node_local_tool "https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/local_db_tool.py"
click node_vector_store "https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/local_db_tool.py"
click node_web_tool "https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/web_search_tool.py"
click node_extractor_model "https://github.com/giharanavindu/truthbomb/blob/dev/src/models/extractor.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_form,node_ticker,node_result,node_sources,node_user toneBlue
class node_api,node_workflow,node_state toneAmber
class node_extractor_agent,node_retrieval_agent,node_local_research,node_web_research,node_adjudicator,node_synthesis,node_translator toneMint
class node_hybrid_tool,node_rag_retriever,node_fusion,node_local_tool,node_vector_store,node_web_tool toneRose
class node_extractor_model,node_news_sources,node_gemini toneIndigo
```

## Components

### User Interface

- [Application UI](https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Claim form](https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/FactCheckerForm.tsx): `frontend/src/components/FactCheckerForm.tsx`
- [News ticker](https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/LatestNewsTicker.tsx): `frontend/src/components/LatestNewsTicker.tsx`
- [Verdict card](https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/ResultCard.tsx): `frontend/src/components/ResultCard.tsx`
- [Context sources](https://github.com/giharanavindu/truthbomb/blob/dev/frontend/src/components/ContextSources.tsx): `frontend/src/components/ContextSources.tsx`

### API and Workflow

- [FastAPI service](https://github.com/giharanavindu/truthbomb/blob/dev/src/main.py): `src/main.py`
- [State workflow](https://github.com/giharanavindu/truthbomb/blob/dev/src/pipeline.py): `src/pipeline.py`
- [Agent state](https://github.com/giharanavindu/truthbomb/blob/dev/src/state.py): `src/state.py`

### Research and Verification

- [Claim extraction](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/claim_extractor.py): `src/agents/claim_extractor.py`
- [Retrieval node](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/retriever.py): `src/agents/retriever.py`
- [Local research](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/local_researcher.py): `src/agents/local_researcher.py`
- [Web research](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/web_researcher.py): `src/agents/web_researcher.py`
- [Adjudication](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/adjudicator.py): `src/agents/adjudicator.py`
- [Verdict synthesis](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/synthesis.py): `src/agents/synthesis.py`
- [Translation](https://github.com/giharanavindu/truthbomb/blob/dev/src/agents/translator.py): `src/agents/translator.py`

### Evidence and Ingestion

- [Hybrid retrieval](https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/hybrid_retriever.py): `src/tools/hybrid_retriever.py`
- [RAG retriever](https://github.com/giharanavindu/truthbomb/blob/dev/src/rag/retriever.py): `src/rag/retriever.py`
- [Rank fusion](https://github.com/giharanavindu/truthbomb/blob/dev/src/rag/fusion.py): `src/rag/fusion.py`
- [Local DB verifier](https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/local_db_tool.py): `src/tools/local_db_tool.py`
- [Chroma store](https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/local_db_tool.py): `src/tools/local_db_tool.py`
- [Trusted web search](https://github.com/giharanavindu/truthbomb/blob/dev/src/tools/web_search_tool.py): `src/tools/web_search_tool.py`

### Language Models

- [GGUF extractor](https://github.com/giharanavindu/truthbomb/blob/dev/src/models/extractor.py): `src/models/extractor.py`

### Other components

- **Fact-check user**
- **Telegram and RSS**
- **Gemini service**

## Connections

- Fact-check user → Claim form: enters claim
- Claim form → Application UI: submits text (evidence: `frontend/src/App.tsx`)
- Application UI → FastAPI service: posts verification (evidence: `frontend/src/App.tsx`)
- FastAPI service → State workflow: runs graph (evidence: `src/main.py`)
- State workflow → Claim extraction: starts extraction (evidence: `src/pipeline.py`)
- State workflow → Retrieval node: dispatches retrieval (evidence: `src/pipeline.py`)
- State workflow → Local research: routes locally (evidence: `src/pipeline.py`)
- State workflow → Web research: routes to web (evidence: `src/pipeline.py`)
- State workflow → Adjudication: dispatches findings (evidence: `src/pipeline.py`)
- State workflow → Translation: translates verdict (evidence: `src/pipeline.py`)
- Claim extraction → GGUF extractor: extracts claim (evidence: `src/agents/claim_extractor.py`)
- Retrieval node → Hybrid retrieval: retrieves evidence (evidence: `src/agents/retriever.py`)
- Local research → Local DB verifier: verifies locally (evidence: `src/agents/local_researcher.py`)
- Local research → Web research: falls back (evidence: `src/agents/local_researcher.py`)
- Web research → Trusted web search: searches web (evidence: `src/agents/web_researcher.py`)
- Hybrid retrieval → Chroma store: queries dense store (evidence: `src/tools/hybrid_retriever.py`)
- Hybrid retrieval → RAG retriever: uses retrieval
- RAG retriever → Rank fusion: fuses rankings (evidence: `src/rag/retriever.py`)
- Local DB verifier → RAG retriever: retrieves context (evidence: `src/tools/local_db_tool.py`)
- Local DB verifier → Chroma store: reads documents (evidence: `src/tools/local_db_tool.py`)
- Telegram and RSS → Chroma store: feeds corpus
- GGUF extractor → Gemini service: uses fallback (evidence: `src/models/extractor.py`)
- Web research → Gemini service: requests verdict (evidence: `src/agents/web_researcher.py`)
- Application UI → News ticker: renders ticker (evidence: `frontend/src/App.tsx`)
- Application UI → Verdict card: renders verdict (evidence: `frontend/src/App.tsx`)
- Application UI → Context sources: renders sources (evidence: `frontend/src/App.tsx`)
- FastAPI service → Application UI: returns response
- Adjudication → Verdict synthesis: may synthesize
