# siddhi0808/groundtruth_ai architecture

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

- Interactive diagram: https://gitdiagram.com/siddhi0808/groundtruth_ai
- Repository: https://github.com/siddhi0808/groundtruth_ai

## Overview

GroundTruth AI is a document-grounded hallucination detector. A user submits a question and an LLM answer through the browser; the API retrieves evidence, asks a judge for a verdict, returns the result, and records detection history. Documents enter through upload or batch ingestion, then are extracted, chunked, embedded, and indexed. The product also exposes health, statistics, history, and dashboard views. The README documents both vector search and degraded SQLite keyword search; unsampled API details are represented only where documented.

Main entry points: [`backend/main.py`](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/main.py) (API handlers), [`backend/rag/ingest.py`](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/ingest.py) (Batch ingestion), [`frontend/script.js`](https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/script.js) (UI client), [`backend/database.py`](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/database.py) (Chunk and history store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_detector["Detector UI<br/>[index.html]"]
  node_dashboard["Dashboard view<br/>[dashboard.html]"]
  node_history_view["History view<br/>[history.html]"]
  node_client["UI client<br/>[script.js]"]
end

subgraph group_api["Detection API"]
  node_api_service["API handlers<br/>[main.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_knowledge["Knowledge indexing and retrieval"]
  node_ingestion["Batch ingestion<br/>[ingest.py]"]
  node_document_loader["Document extraction<br/>[document_loader.py]"]
  node_chunker["Token chunking<br/>[chunker.py]"]
  node_embeddings["Embedding model<br/>[embeddings.py]"]
  node_retriever["Evidence retrieval<br/>[retriever.py]"]
end

subgraph group_judging["Verdict and persistence"]
  node_judge["Verdict judge<br/>[judge.py]"]
  node_database[("Chunk and history store<br/>[database.py]")]
end

node_user(("User"))
node_browser(("Browser"))
node_ollama["Ollama"]

node_user -->|"uses"| node_browser
node_browser -->|"opens"| node_detector
node_detector -->|"runs"| node_client
node_client -->|"submits detection"| node_api_service
node_api_service -->|"returns verdict"| node_client
node_api_service -->|"retrieves evidence"| node_retriever
node_api_service -->|"judges answer"| node_judge
node_api_service -->|"records detections"| node_database
node_api_service -->|"extracts uploads"| node_document_loader
node_api_service -->|"indexes uploads"| node_ingestion
node_ingestion -->|"loads documents"| node_document_loader
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"embeds chunks"| node_embeddings
node_ingestion -->|"inserts chunks"| node_database
node_chunker -->|"measures tokens"| node_embeddings
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"searches chunks"| node_database
node_database -->|"reads settings"| node_config
node_api_service -->|"reads settings"| node_config
node_judge -->|"reads settings"| node_config
node_judge -->|"requests judgment"| node_ollama
node_api_service -->|"serves page"| node_dashboard
node_api_service -->|"serves page"| node_history_view
node_browser -->|"opens"| node_dashboard
node_browser -->|"opens"| node_history_view
node_client -->|"requests upload"| node_api_service
node_client -->|"requests history and stats"| node_api_service

click node_detector "https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/index.html"
click node_dashboard "https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/dashboard.html"
click node_history_view "https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/history.html"
click node_client "https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/script.js"
click node_api_service "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/main.py"
click node_config "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/config.py"
click node_ingestion "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/ingest.py"
click node_document_loader "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/document_loader.py"
click node_chunker "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/chunker.py"
click node_embeddings "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/embeddings.py"
click node_retriever "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/retriever.py"
click node_judge "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/llm/judge.py"
click node_database "https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/database.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_detector,node_dashboard,node_history_view,node_client,node_user,node_browser toneBlue
class node_api_service,node_config toneAmber
class node_ingestion,node_document_loader,node_chunker,node_embeddings,node_retriever toneMint
class node_judge,node_database toneRose
class node_ollama toneIndigo
```

## Components

### User experience

- [Detector UI](https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/index.html): `frontend/index.html`
- [Dashboard view](https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/dashboard.html): `frontend/dashboard.html`
- [History view](https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/history.html): `frontend/history.html`
- [UI client](https://github.com/siddhi0808/groundtruth_ai/blob/main/frontend/script.js): `frontend/script.js`

### Detection API

- [API handlers](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/main.py): `backend/main.py`
- [Runtime config](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/config.py): `backend/config.py`

### Knowledge indexing and retrieval

- [Batch ingestion](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/ingest.py): `backend/rag/ingest.py`
- [Document extraction](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/document_loader.py): `backend/rag/document_loader.py`
- [Token chunking](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/chunker.py): `backend/rag/chunker.py`
- [Embedding model](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/embeddings.py): `backend/rag/embeddings.py`
- [Evidence retrieval](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/rag/retriever.py): `backend/rag/retriever.py`

### Verdict and persistence

- [Verdict judge](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/llm/judge.py): `backend/llm/judge.py`
- [Chunk and history store](https://github.com/siddhi0808/groundtruth_ai/blob/main/backend/database.py): `backend/database.py`

### Other components

- **User**
- **Browser**
- **Ollama**

## Connections

- User → Browser: uses (evidence: `README.md`)
- Browser → Detector UI: opens (evidence: `README.md`)
- Detector UI → UI client: runs (evidence: `frontend/script.js`)
- UI client → API handlers: submits detection (evidence: `frontend/script.js`)
- API handlers → UI client: returns verdict (evidence: `README.md`)
- API handlers → Evidence retrieval: retrieves evidence (evidence: `backend/main.py`)
- API handlers → Verdict judge: judges answer (evidence: `backend/main.py`)
- API handlers → Chunk and history store: records detections (evidence: `backend/main.py`)
- API handlers → Document extraction: extracts uploads (evidence: `README.md`)
- API handlers → Batch ingestion: indexes uploads (evidence: `backend/main.py`)
- Batch ingestion → Document extraction: loads documents (evidence: `backend/rag/ingest.py`)
- Batch ingestion → Token chunking: chunks text (evidence: `backend/rag/ingest.py`)
- Batch ingestion → Embedding model: embeds chunks (evidence: `backend/rag/ingest.py`)
- Batch ingestion → Chunk and history store: inserts chunks (evidence: `backend/rag/ingest.py`)
- Token chunking → Embedding model: measures tokens (evidence: `backend/rag/chunker.py`)
- Evidence retrieval → Embedding model: embeds query (evidence: `backend/rag/retriever.py`)
- Evidence retrieval → Chunk and history store: searches chunks (evidence: `backend/rag/retriever.py`)
- Chunk and history store → Runtime config: reads settings (evidence: `backend/database.py`)
- API handlers → Runtime config: reads settings (evidence: `backend/main.py`)
- Verdict judge → Runtime config: reads settings (evidence: `backend/llm/judge.py`)
- Verdict judge → Ollama: requests judgment (evidence: `backend/llm/judge.py`)
- API handlers → Dashboard view: serves page (evidence: `backend/main.py`)
- API handlers → History view: serves page (evidence: `backend/main.py`)
- Browser → Dashboard view: opens (evidence: `README.md`)
- Browser → History view: opens (evidence: `README.md`)
- UI client → API handlers: requests upload (evidence: `frontend/script.js`)
- UI client → API handlers: requests history and stats (evidence: `README.md`)