# ayushdevadiga1/insight-swarm architecture

> Architecture diagram of the GitHub repository ayushdevadiga1/insight-swarm, 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/ayushdevadiga1/insight-swarm
- Repository: https://github.com/ayushdevadiga1/insight-swarm

## Overview

InsightSwarm is a multi-agent fact-checking application with a React interface, FastAPI gateway, and debate orchestrator. Users submit a claim; the pipeline estimates complexity, decomposes compound claims, retrieves evidence, runs adversarial arguments and source verification, may pause for human review, then produces a moderated, calibrated verdict that streams to the UI. The graph preserves the README’s documented research and result capabilities. Some pipeline wiring is documented rather than visible in sampled code; unsampled implementation details are not inferred.

Main entry points: [`src/orchestration/debate.py`](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/orchestration/debate.py) (Debate orchestrator), [`src/llm/client.py`](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/llm/client.py) (LLM client), [`frontend/src/App.jsx`](https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/App.jsx) (Debate interface), [`api/server.py`](https://github.com/ayushdevadiga1/insight-swarm/blob/main/api/server.py) (REST and SSE API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["Debate interface<br/>[App.jsx]"]
  node_stream["Live event hook<br/>[useSSE.js]"]
  node_debate_state["Debate state<br/>[useDebateStore.js]"]
  node_review_ui["Human review panel<br/>[HITLPanel.jsx]"]
  node_result_ui["Verdict and metrics<br/>[MetricsGrid.jsx]"]
end

subgraph group_gateway["API gateway"]
  node_api["REST and SSE API<br/>[server.py]"]
end

subgraph group_debate["Claim analysis"]
  node_orchestrator["Debate orchestrator<br/>[debate.py]"]
  node_complexity["Claim complexity"]
  node_decomposer["Sub-claim decomposition"]
  node_pro_agent["Pro agent<br/>[pro_agent.py]"]
  node_con_agent["Con agent<br/>[con_agent.py]"]
  node_summarizer["Debate summarizer<br/>[summarizer.py]"]
end

subgraph group_evidence["Evidence and results"]
  node_retrieval["Evidence retrieval"]
  node_fact_checker["Source verification<br/>[fact_checker.py]"]
  node_moderator["Verdict moderation<br/>[moderator.py]"]
  node_argument_analysis["Fallacy analysis"]
  node_calibrator["Confidence calibration"]
  node_explainability["Verdict explainability<br/>[explainability.py]"]
end

subgraph group_infra["Runtime services"]
  node_cache[("Claim cache<br/>[cache.py]")]
  node_llm["LLM client<br/>[client.py]"]
end

node_user(("Claim submitter"))
node_providers{{"LLM providers"}}
node_web_sources{{"Web sources"}}

node_user -->|"submits claim"| node_app
node_app -->|"starts stream"| node_stream
node_stream -->|"opens /stream"| node_api
node_api -->|"runs debate"| node_orchestrator
node_orchestrator -->|"estimates depth"| node_complexity
node_orchestrator -->|"decomposes claim"| node_decomposer
node_orchestrator -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"searches"| node_web_sources
node_orchestrator -->|"dispatches"| node_pro_agent
node_orchestrator -->|"dispatches"| node_con_agent
node_orchestrator -->|"summarizes rounds"| node_summarizer
node_orchestrator -->|"verifies sources"| node_fact_checker
node_fact_checker -->|"fetches cited URLs"| node_web_sources
node_orchestrator -->|"requests verdict"| node_moderator
node_moderator -->|"analyzes arguments"| node_argument_analysis
node_moderator -->|"calibrates confidence"| node_calibrator
node_orchestrator -->|"explains verdict"| node_explainability
node_orchestrator -->|"reads and writes"| node_cache
node_pro_agent -->|"requests completion"| node_llm
node_con_agent -->|"requests completion"| node_llm
node_fact_checker -->|"requests completion"| node_llm
node_moderator -->|"requests completion"| node_llm
node_llm -->|"calls providers"| node_providers
node_api -->|"emits debate events"| node_stream
node_stream -->|"updates state"| node_debate_state
node_app -->|"renders review"| node_review_ui
node_app -->|"renders results"| node_result_ui
node_api -.->|"resumes review"| node_orchestrator

click node_app "https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/App.jsx"
click node_stream "https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/hooks/useSSE.js"
click node_debate_state "https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/store/useDebateStore.js"
click node_review_ui "https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/components/hitl/HITLPanel.jsx"
click node_result_ui "https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/components/results/MetricsGrid.jsx"
click node_api "https://github.com/ayushdevadiga1/insight-swarm/blob/main/api/server.py"
click node_orchestrator "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/orchestration/debate.py"
click node_complexity "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/claim_complexity.py"
click node_decomposer "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/utils/claim_decomposer.py"
click node_pro_agent "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/pro_agent.py"
click node_con_agent "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/con_agent.py"
click node_summarizer "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/utils/summarizer.py"
click node_retrieval "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/utils/tavily_retriever.py"
click node_fact_checker "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/fact_checker.py"
click node_moderator "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/moderator.py"
click node_argument_analysis "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/argumentation_analysis.py"
click node_calibrator "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/confidence_calibration.py"
click node_explainability "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/explainability.py"
click node_cache "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/orchestration/cache.py"
click node_llm "https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/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_app,node_stream,node_debate_state,node_review_ui,node_result_ui toneBlue
class node_api toneAmber
class node_orchestrator,node_complexity,node_decomposer,node_pro_agent,node_con_agent,node_summarizer toneMint
class node_retrieval,node_fact_checker,node_moderator,node_argument_analysis,node_calibrator,node_explainability toneRose
class node_cache,node_llm,node_user,node_providers,node_web_sources toneIndigo
```

## Components

### User interface

- [Debate interface](https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Live event hook](https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/hooks/useSSE.js): `frontend/src/hooks/useSSE.js`
- [Debate state](https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/store/useDebateStore.js): `frontend/src/store/useDebateStore.js`
- [Human review panel](https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/components/hitl/HITLPanel.jsx): `frontend/src/components/hitl/HITLPanel.jsx`
- [Verdict and metrics](https://github.com/ayushdevadiga1/insight-swarm/blob/main/frontend/src/components/results/MetricsGrid.jsx): `frontend/src/components/results/MetricsGrid.jsx`

### API gateway

- [REST and SSE API](https://github.com/ayushdevadiga1/insight-swarm/blob/main/api/server.py): `api/server.py`

### Claim analysis

- [Debate orchestrator](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/orchestration/debate.py): `src/orchestration/debate.py`
- [Claim complexity](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/claim_complexity.py): `src/novelty/claim_complexity.py`
- [Sub-claim decomposition](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/utils/claim_decomposer.py): `src/utils/claim_decomposer.py`
- [Pro agent](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/pro_agent.py): `src/agents/pro_agent.py`
- [Con agent](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/con_agent.py): `src/agents/con_agent.py`
- [Debate summarizer](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/utils/summarizer.py): `src/utils/summarizer.py`

### Evidence and results

- [Evidence retrieval](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/utils/tavily_retriever.py): `src/utils/tavily_retriever.py`
- [Source verification](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/fact_checker.py): `src/agents/fact_checker.py`
- [Verdict moderation](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/agents/moderator.py): `src/agents/moderator.py`
- [Fallacy analysis](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/argumentation_analysis.py): `src/novelty/argumentation_analysis.py`
- [Confidence calibration](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/confidence_calibration.py): `src/novelty/confidence_calibration.py`
- [Verdict explainability](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/novelty/explainability.py): `src/novelty/explainability.py`

### Runtime services

- [Claim cache](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/orchestration/cache.py): `src/orchestration/cache.py`
- [LLM client](https://github.com/ayushdevadiga1/insight-swarm/blob/main/src/llm/client.py): `src/llm/client.py`

### Other components

- **Claim submitter**
- **LLM providers**
- **Web sources**

## Connections

- Claim submitter → Debate interface: submits claim
- Debate interface → Live event hook: starts stream (evidence: `frontend/src/App.jsx`)
- Live event hook → REST and SSE API: opens /stream (evidence: `frontend/src/hooks/useSSE.js`)
- REST and SSE API → Debate orchestrator: runs debate (evidence: `api/server.py`)
- Debate orchestrator → Claim complexity: estimates depth
- Debate orchestrator → Sub-claim decomposition: decomposes claim (evidence: `src/orchestration/debate.py`)
- Debate orchestrator → Evidence retrieval: retrieves evidence (evidence: `src/orchestration/debate.py`)
- Evidence retrieval → Web sources: searches
- Debate orchestrator → Pro agent: dispatches (evidence: `src/orchestration/debate.py`)
- Debate orchestrator → Con agent: dispatches (evidence: `src/orchestration/debate.py`)
- Debate orchestrator → Debate summarizer: summarizes rounds (evidence: `src/orchestration/debate.py`)
- Debate orchestrator → Source verification: verifies sources (evidence: `src/orchestration/debate.py`)
- Source verification → Web sources: fetches cited URLs (evidence: `src/agents/fact_checker.py`)
- Debate orchestrator → Verdict moderation: requests verdict (evidence: `src/orchestration/debate.py`)
- Verdict moderation → Fallacy analysis: analyzes arguments
- Verdict moderation → Confidence calibration: calibrates confidence
- Debate orchestrator → Verdict explainability: explains verdict
- Debate orchestrator → Claim cache: reads and writes (evidence: `src/orchestration/debate.py`)
- Pro agent → LLM client: requests completion (evidence: `src/agents/pro_agent.py`)
- Con agent → LLM client: requests completion (evidence: `src/agents/con_agent.py`)
- Source verification → LLM client: requests completion (evidence: `src/agents/fact_checker.py`)
- Verdict moderation → LLM client: requests completion (evidence: `src/agents/moderator.py`)
- LLM client → LLM providers: calls providers
- REST and SSE API → Live event hook: emits debate events
- Live event hook → Debate state: updates state (evidence: `frontend/src/hooks/useSSE.js`)
- Debate interface → Human review panel: renders review (evidence: `frontend/src/App.jsx`)
- Debate interface → Verdict and metrics: renders results (evidence: `frontend/src/App.jsx`)
- REST and SSE API → Debate orchestrator: resumes review (evidence: `api/server.py`)
