# alen-saji-05/real-time-halu-detect architecture

> Architecture diagram of the GitHub repository alen-saji-05/real-time-halu-detect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alen-saji-05/real-time-halu-detect
- Repository: https://github.com/alen-saji-05/real-time-halu-detect

## Overview

HalluGuard combines a browser extension and Flask-backed workflow that gathers evidence for an answer, detects unsupported answer spans, and returns results to the page. A separate detection API exposes the detector directly. The main workflow and detector internals are supported by sampled source; web UI wiring and some extension presentation behavior are only represented where the tree or excerpts identify them.

Main entry points: [`main.py`](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/main.py) (QA pipeline), [`app.py`](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/app.py) (Pipeline API), [`extension/background.js`](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/background.js) (Extension worker), [`halluguard/detectors/transformer.py`](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/transformer.py) (Transformer detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser extension"]
  node_content["Page monitor<br/>[content.js]"]
  node_background["Extension worker<br/>[background.js]"]
  node_popup["Extension popup<br/>[popup.js]"]
end

subgraph group_pipeline["Evidence pipeline"]
  node_pipeline["QA pipeline<br/>[main.py]"]
  node_keywords["Keyword extraction"]
  node_context["Context retrieval"]
end

subgraph group_detection["Detection engine"]
  node_facade["Detector façade<br/>[inference.py]"]
  node_factory["Detector factory<br/>[factory.py]"]
  node_transformer["Transformer detector<br/>[transformer.py]"]
  node_base["Detector interface<br/>[base.py]"]
  node_dataset["Token preparation"]
end

subgraph group_services["HTTP services"]
  node_pipeline_api["Pipeline API<br/>[app.py]"]
  node_detector_api["Detector API<br/>[server.py]"]
  node_results[("Saved results<br/>[app.py]")]
  node_webapp["Web application<br/>[webapp.py]"]
end

node_user(("Chat user"))
node_chat["AI chat page"]
node_serp["SERP search"]
node_wiki["Wikipedia content"]
node_model["Classifier model"]

node_user -->|"asks question"| node_chat
node_chat -->|"renders response"| node_content
node_content -->|"sends Q&amp;A"| node_background
node_background -->|"POSTs Q&amp;A"| node_pipeline_api
node_pipeline_api -->|"saves Q&amp;A/results"| node_results
node_pipeline_api -->|"runs pipeline"| node_pipeline
node_pipeline -->|"extracts keywords"| node_keywords
node_pipeline -->|"retrieves context"| node_context
node_context -->|"searches web"| node_serp
node_context -->|"fetches articles"| node_wiki
node_pipeline -->|"checks answer"| node_facade
node_facade -->|"creates detector"| node_factory
node_factory -->|"selects implementation"| node_transformer
node_transformer -.->|"implements interface"| node_base
node_transformer -->|"prepares tokens"| node_dataset
node_transformer -->|"runs inference"| node_model
node_pipeline -->|"returns analysis"| node_pipeline_api
node_pipeline_api -->|"returns detection"| node_background
node_background -->|"forwards results"| node_content
node_content -->|"shows findings"| node_chat
node_detector_api -->|"predicts spans"| node_facade
node_popup -->|"reads state"| node_background
node_webapp -.->|"reads results"| node_results

click node_content "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/content.js"
click node_background "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/background.js"
click node_popup "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/popup.js"
click node_pipeline_api "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/app.py"
click node_pipeline "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/main.py"
click node_keywords "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/keyword_extractor.py"
click node_context "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/context_genarator.py"
click node_detector_api "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/server.py"
click node_facade "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/models/inference.py"
click node_factory "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/factory.py"
click node_transformer "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/transformer.py"
click node_base "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/base.py"
click node_dataset "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/datasets/hallucination_dataset.py"
click node_results "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/app.py"
click node_webapp "https://github.com/alen-saji-05/real-time-halu-detect/blob/main/webapp.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_content,node_background,node_popup,node_user toneBlue
class node_pipeline,node_keywords,node_context toneAmber
class node_facade,node_factory,node_transformer,node_base,node_dataset toneMint
class node_pipeline_api,node_detector_api,node_results,node_webapp toneRose
class node_chat,node_serp,node_wiki,node_model toneIndigo
```

## Components

### Browser extension

- [Page monitor](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/content.js): `extension/content.js`
- [Extension worker](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/background.js): `extension/background.js`
- [Extension popup](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/extension/popup.js): `extension/popup.js`

### Evidence pipeline

- [QA pipeline](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/main.py): `main.py`
- [Keyword extraction](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/keyword_extractor.py): `keyword_extractor.py`
- [Context retrieval](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/context_genarator.py): `context_genarator.py`

### Detection engine

- [Detector façade](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/models/inference.py): `halluguard/models/inference.py`
- [Detector factory](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/factory.py): `halluguard/detectors/factory.py`
- [Transformer detector](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/transformer.py): `halluguard/detectors/transformer.py`
- [Detector interface](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/detectors/base.py): `halluguard/detectors/base.py`
- [Token preparation](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/halluguard/datasets/hallucination_dataset.py): `halluguard/datasets/hallucination_dataset.py`

### HTTP services

- [Pipeline API](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/app.py): `app.py`
- [Detector API](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/server.py): `server.py`
- [Saved results](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/app.py): `app.py`
- [Web application](https://github.com/alen-saji-05/real-time-halu-detect/blob/main/webapp.py): `webapp.py`

### Other components

- **Chat user**
- **AI chat page**
- **SERP search**
- **Wikipedia content**
- **Classifier model**

## Connections

- Chat user → AI chat page: asks question
- AI chat page → Page monitor: renders response
- Page monitor → Extension worker: sends Q&A
- Extension worker → Pipeline API: POSTs Q&A
- Pipeline API → Saved results: saves Q&A/results
- Pipeline API → QA pipeline: runs pipeline
- QA pipeline → Keyword extraction: extracts keywords
- QA pipeline → Context retrieval: retrieves context
- Context retrieval → SERP search: searches web
- Context retrieval → Wikipedia content: fetches articles
- QA pipeline → Detector façade: checks answer
- Detector façade → Detector factory: creates detector
- Detector factory → Transformer detector: selects implementation
- Transformer detector → Detector interface: implements interface
- Transformer detector → Token preparation: prepares tokens
- Transformer detector → Classifier model: runs inference
- QA pipeline → Pipeline API: returns analysis
- Pipeline API → Extension worker: returns detection
- Extension worker → Page monitor: forwards results
- Page monitor → AI chat page: shows findings
- Detector API → Detector façade: predicts spans
- Extension popup → Extension worker: reads state
- Web application → Saved results: reads results