# mahyarrk/project-veritas architecture

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

- Interactive diagram: https://gitdiagram.com/mahyarrk/project-veritas
- Repository: https://github.com/mahyarrk/project-veritas

## Overview

project-veritas audits published statistics against supplied raw data and also provides cited RAG chat about the paper. The principal audit flow is paper/data input through ingestion, LLM-proposed statistics with deterministic validation, then a deterministic recomputation and human-resolvable verdict report. The separate chat flow retrieves provenance-bearing excerpts and answers questions about the paper. Edges reflect README statements, shown calls, or SOURCE INDEX references; some GUI and ingestion internals were only partially excerpted.

Main entry points: [`ingest.py`](https://github.com/mahyarrk/project-veritas/blob/main/ingest.py) (Document ingestion), [`main.py`](https://github.com/mahyarrk/project-veritas/blob/main/main.py) (CLI workflow), [`chat.py`](https://github.com/mahyarrk/project-veritas/blob/main/chat.py) (Grounded answer), [`extract.py`](https://github.com/mahyarrk/project-veritas/blob/main/extract.py) (Statistic extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_gui["Streamlit UI<br/>[gui.py]"]
  node_cli["CLI workflow<br/>[main.py]"]
end

subgraph group_audit["Statistics audit"]
  node_extract["Statistic extraction<br/>[extract.py]"]
  node_extractmodel{{"Extraction LLM"}}
  node_gauntlet["Proposal validation<br/>[extract.py]"]
  node_battery["Statistic battery<br/>[verify.py]"]
  node_resolution["Match and resolve<br/>[verify.py]"]
  node_report["Audit report<br/>[verify.py]"]
end

subgraph group_rag["Paper RAG chat"]
  node_query["Question and rewrite<br/>[chat.py]"]
  node_retrieval["Provenance retrieval<br/>[retrieve.py]"]
  node_chatanswer["Grounded answer<br/>[chat.py]"]
  node_chatmodel{{"Chat LLM"}}
  node_history[("Chat history<br/>[chat.py]")]
end

subgraph group_shared["Shared services"]
  node_setup["Endpoint setup<br/>[setup.py]"]
  node_ingestion["Document ingestion<br/>[ingest.py]"]
  node_embeddings["Embedding service<br/>[ingest.py]"]
  node_store[("Chunk and dataset store<br/>[ingest.py]")]
end

node_user(("Researcher"))
node_paper["Paper input"]
node_rawdata["Raw data"]

node_user -->|"uses"| node_gui
node_user -->|"runs"| node_cli
node_user -->|"provides"| node_paper
node_user -->|"provides"| node_rawdata
node_cli -->|"configures"| node_setup
node_cli -->|"processes inputs"| node_ingestion
node_paper -->|"loads text"| node_ingestion
node_rawdata -->|"loads schema"| node_ingestion
node_ingestion -->|"embeds chunks"| node_embeddings
node_ingestion -->|"writes"| node_store
node_cli -->|"runs extraction"| node_extract
node_extract -->|"requests proposals"| node_extractmodel
node_extract -->|"loads paper"| node_ingestion
node_extract -->|"validates proposals"| node_gauntlet
node_cli -->|"runs audit"| node_battery
node_battery -->|"matches values"| node_resolution
node_resolution -->|"records verdicts"| node_report
node_battery -->|"recomputes from"| node_rawdata
node_gui -->|"invokes"| node_extract
node_gui -->|"invokes"| node_battery
node_gui -->|"requests answers"| node_chatanswer
node_user -->|"asks"| node_query
node_query -->|"searches"| node_retrieval
node_retrieval -->|"reads chunks"| node_store
node_retrieval -->|"embeds query"| node_embeddings
node_chatanswer -->|"uses excerpts"| node_retrieval
node_chatanswer -->|"generates answer"| node_chatmodel
node_chatanswer -->|"persists turns"| node_history
node_chatanswer -->|"returns cited answer"| node_user

click node_gui "https://github.com/mahyarrk/project-veritas/blob/main/gui.py"
click node_cli "https://github.com/mahyarrk/project-veritas/blob/main/main.py"
click node_setup "https://github.com/mahyarrk/project-veritas/blob/main/setup.py"
click node_ingestion "https://github.com/mahyarrk/project-veritas/blob/main/ingest.py"
click node_embeddings "https://github.com/mahyarrk/project-veritas/blob/main/ingest.py"
click node_store "https://github.com/mahyarrk/project-veritas/blob/main/ingest.py"
click node_extract "https://github.com/mahyarrk/project-veritas/blob/main/extract.py"
click node_gauntlet "https://github.com/mahyarrk/project-veritas/blob/main/extract.py"
click node_battery "https://github.com/mahyarrk/project-veritas/blob/main/verify.py"
click node_resolution "https://github.com/mahyarrk/project-veritas/blob/main/verify.py"
click node_report "https://github.com/mahyarrk/project-veritas/blob/main/verify.py"
click node_query "https://github.com/mahyarrk/project-veritas/blob/main/chat.py"
click node_retrieval "https://github.com/mahyarrk/project-veritas/blob/main/retrieve.py"
click node_chatanswer "https://github.com/mahyarrk/project-veritas/blob/main/chat.py"
click node_history "https://github.com/mahyarrk/project-veritas/blob/main/chat.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_gui,node_cli toneBlue
class node_extract,node_extractmodel,node_gauntlet,node_battery,node_resolution,node_report toneAmber
class node_query,node_retrieval,node_chatanswer,node_chatmodel,node_history toneMint
class node_setup,node_ingestion,node_embeddings,node_store toneRose
class node_user,node_paper,node_rawdata toneIndigo
```

## Components

### User entry points

- [Streamlit UI](https://github.com/mahyarrk/project-veritas/blob/main/gui.py): `gui.py`
- [CLI workflow](https://github.com/mahyarrk/project-veritas/blob/main/main.py): `main.py`

### Statistics audit

- [Statistic extraction](https://github.com/mahyarrk/project-veritas/blob/main/extract.py): `extract.py`
- **Extraction LLM**
- [Proposal validation](https://github.com/mahyarrk/project-veritas/blob/main/extract.py): `extract.py`
- [Statistic battery](https://github.com/mahyarrk/project-veritas/blob/main/verify.py): `verify.py`
- [Match and resolve](https://github.com/mahyarrk/project-veritas/blob/main/verify.py): `verify.py`
- [Audit report](https://github.com/mahyarrk/project-veritas/blob/main/verify.py): `verify.py`

### Paper RAG chat

- [Question and rewrite](https://github.com/mahyarrk/project-veritas/blob/main/chat.py): `chat.py`
- [Provenance retrieval](https://github.com/mahyarrk/project-veritas/blob/main/retrieve.py): `retrieve.py`
- [Grounded answer](https://github.com/mahyarrk/project-veritas/blob/main/chat.py): `chat.py`
- **Chat LLM**
- [Chat history](https://github.com/mahyarrk/project-veritas/blob/main/chat.py): `chat.py`

### Shared services

- [Endpoint setup](https://github.com/mahyarrk/project-veritas/blob/main/setup.py): `setup.py`
- [Document ingestion](https://github.com/mahyarrk/project-veritas/blob/main/ingest.py): `ingest.py`
- [Embedding service](https://github.com/mahyarrk/project-veritas/blob/main/ingest.py): `ingest.py`
- [Chunk and dataset store](https://github.com/mahyarrk/project-veritas/blob/main/ingest.py): `ingest.py`

### Other components

- **Researcher**
- **Paper input**
- **Raw data**

## Connections

- Researcher → Streamlit UI: uses (evidence: `README.md`)
- Researcher → CLI workflow: runs (evidence: `README.md`)
- Researcher → Paper input: provides (evidence: `README.md`)
- Researcher → Raw data: provides (evidence: `README.md`)
- CLI workflow → Endpoint setup: configures (evidence: `main.py`)
- CLI workflow → Document ingestion: processes inputs (evidence: `main.py`)
- Paper input → Document ingestion: loads text (evidence: `README.md`)
- Raw data → Document ingestion: loads schema (evidence: `README.md`)
- Document ingestion → Embedding service: embeds chunks (evidence: `ingest.py`)
- Document ingestion → Chunk and dataset store: writes (evidence: `ingest.py`)
- CLI workflow → Statistic extraction: runs extraction (evidence: `main.py`)
- Statistic extraction → Extraction LLM: requests proposals (evidence: `extract.py`)
- Statistic extraction → Document ingestion: loads paper (evidence: `extract.py`)
- Statistic extraction → Proposal validation: validates proposals (evidence: `extract.py`)
- CLI workflow → Statistic battery: runs audit (evidence: `main.py`)
- Statistic battery → Match and resolve: matches values (evidence: `verify.py`)
- Match and resolve → Audit report: records verdicts (evidence: `verify.py`)
- Statistic battery → Raw data: recomputes from (evidence: `README.md`)
- Streamlit UI → Statistic extraction: invokes (evidence: `gui.py`)
- Streamlit UI → Statistic battery: invokes (evidence: `gui.py`)
- Streamlit UI → Grounded answer: requests answers (evidence: `gui.py`)
- Researcher → Question and rewrite: asks (evidence: `README.md`)
- Question and rewrite → Provenance retrieval: searches (evidence: `chat.py`)
- Provenance retrieval → Chunk and dataset store: reads chunks (evidence: `retrieve.py`)
- Provenance retrieval → Embedding service: embeds query (evidence: `retrieve.py`)
- Grounded answer → Provenance retrieval: uses excerpts (evidence: `chat.py`)
- Grounded answer → Chat LLM: generates answer (evidence: `chat.py`)
- Grounded answer → Chat history: persists turns (evidence: `chat.py`)
- Grounded answer → Researcher: returns cited answer (evidence: `README.md`)
