# dheeraj00001/se-mini-project architecture

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

- Interactive diagram: https://gitdiagram.com/dheeraj00001/se-mini-project
- Repository: https://github.com/dheeraj00001/se-mini-project

## Overview

Dehallucination is a verification gateway with two user-facing flows: an OpenAI-compatible completion proxy that buffers generated text before verification and mitigation, and a /verify sidecar for submitted text. Both feed claim segmentation, tiered grounding, NLI scoring, and safety handling; document ingestion builds the local grounding index. The React frontend provides a live playground and architecture/benchmark views. Some backend links are supported by the README or SOURCE INDEX rather than complete excerpts; unsampled internals are not expanded.

Main entry points: [`src/gateway/router.py`](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/router.py) (API routes), [`src/verifier/orchestrator.py`](https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/orchestrator.py) (Waterfall verifier), [`src/retrieval/ingest.py`](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/ingest.py) (Document ingestion), [`src/retrieval/adapters.py`](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/adapters.py) (Tiered retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Client Interface"]
  node_frontend["React interface<br/>[App.tsx]"]
  node_playground["Verification playground<br/>[Playground.tsx]"]
  node_frontendapi["Frontend API client<br/>[api.ts]"]
end

subgraph group_gateway["Gateway"]
  node_gatewayapp["FastAPI app<br/>[app.py]"]
  node_router["API routes<br/>[router.py]"]
  node_middleware["Header overrides<br/>[middleware.py]"]
  node_buffer["Response buffer<br/>[buffer.py]"]
  node_sse["SSE replay<br/>[sse.py]"]
end

subgraph group_verification["Verification"]
  node_segmenter["Claim segmentation<br/>[segmenter.py]"]
  node_orchestrator["Waterfall verifier<br/>[orchestrator.py]"]
  node_nli["NLI scoring<br/>[nli.py]"]
  node_schemas["Verification contracts<br/>[verification.py]"]
end

subgraph group_grounding["Grounding"]
  node_retrieval["Tiered retrieval<br/>[adapters.py]"]
  node_store[("Dual-index store<br/>[store.py]")]
  node_fusion["Rank fusion<br/>[fusion.py]"]
  node_ingestroute["Knowledge ingest route<br/>[router.py]"]
  node_ingest["Document ingestion<br/>[ingest.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_chunker["Text chunker<br/>[chunker.py]"]
end

subgraph group_safety["Mitigation"]
  node_pipeline["Mitigation pipeline<br/>[pipeline.py]"]
  node_rewriter["Targeted rewriter<br/>[rewriter.py]"]
  node_generator["Local generator<br/>[generator.py]"]
  node_fallback["Safety fallback<br/>[fallback.py]"]
end

node_client(("Client"))
node_upstream["Model provider"]

node_client -->|"uses"| node_frontend
node_frontend -->|"renders"| node_playground
node_playground -->|"calls"| node_frontendapi
node_frontendapi -.->|"HTTP requests"| node_router
node_client -->|"requests"| node_gatewayapp
node_gatewayapp -->|"registers routes"| node_router
node_router -->|"parses overrides"| node_middleware
node_router -->|"buffers output"| node_buffer
node_router -->|"builds stream"| node_sse
node_router -->|"proxies generation"| node_upstream
node_router -->|"verifies claims"| node_orchestrator
node_router -->|"ingests documents"| node_ingest
node_ingest -->|"extracts text"| node_parser
node_ingest -->|"chunks text"| node_chunker
node_ingest -->|"persists chunks"| node_store
node_orchestrator -->|"segments claims"| node_segmenter
node_orchestrator -->|"retrieves evidence"| node_retrieval
node_orchestrator -->|"scores evidence"| node_nli
node_retrieval -->|"searches indexes"| node_store
node_retrieval -->|"fuses rankings"| node_fusion
node_orchestrator -->|"mitigates results"| node_pipeline
node_pipeline -->|"rewrites claims"| node_rewriter
node_rewriter -->|"generates correction"| node_generator
node_pipeline -->|"falls back"| node_fallback
node_client -->|"submits references"| node_ingestroute
node_orchestrator -->|"returns reports"| node_schemas

click node_frontend "https://github.com/dheeraj00001/se-mini-project/blob/main/frontend/src/App.tsx"
click node_playground "https://github.com/dheeraj00001/se-mini-project/blob/main/frontend/src/components/Playground.tsx"
click node_frontendapi "https://github.com/dheeraj00001/se-mini-project/blob/main/frontend/src/services/api.ts"
click node_gatewayapp "https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/app.py"
click node_router "https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/router.py"
click node_middleware "https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/middleware.py"
click node_buffer "https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/buffer.py"
click node_sse "https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/sse.py"
click node_segmenter "https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/segmenter.py"
click node_orchestrator "https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/orchestrator.py"
click node_nli "https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/nli.py"
click node_schemas "https://github.com/dheeraj00001/se-mini-project/blob/main/src/schemas/verification.py"
click node_retrieval "https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/adapters.py"
click node_store "https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/store.py"
click node_fusion "https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/fusion.py"
click node_ingestroute "https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/router.py"
click node_ingest "https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/ingest.py"
click node_parser "https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/parser.py"
click node_chunker "https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/chunker.py"
click node_pipeline "https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/pipeline.py"
click node_rewriter "https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/rewriter.py"
click node_generator "https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/generator.py"
click node_fallback "https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/fallback.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_frontend,node_playground,node_frontendapi,node_client toneBlue
class node_gatewayapp,node_router,node_middleware,node_buffer,node_sse toneAmber
class node_segmenter,node_orchestrator,node_nli,node_schemas toneMint
class node_retrieval,node_store,node_fusion,node_ingestroute,node_ingest,node_parser,node_chunker toneRose
class node_pipeline,node_rewriter,node_generator,node_fallback,node_upstream toneIndigo
```

## Components

### Client Interface

- [React interface](https://github.com/dheeraj00001/se-mini-project/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Verification playground](https://github.com/dheeraj00001/se-mini-project/blob/main/frontend/src/components/Playground.tsx): `frontend/src/components/Playground.tsx`
- [Frontend API client](https://github.com/dheeraj00001/se-mini-project/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Gateway

- [FastAPI app](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/app.py): `src/gateway/app.py`
- [API routes](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/router.py): `src/gateway/router.py`
- [Header overrides](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/middleware.py): `src/gateway/middleware.py`
- [Response buffer](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/buffer.py): `src/gateway/buffer.py`
- [SSE replay](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/sse.py): `src/gateway/sse.py`

### Verification

- [Claim segmentation](https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/segmenter.py): `src/verifier/segmenter.py`
- [Waterfall verifier](https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/orchestrator.py): `src/verifier/orchestrator.py`
- [NLI scoring](https://github.com/dheeraj00001/se-mini-project/blob/main/src/verifier/nli.py): `src/verifier/nli.py`
- [Verification contracts](https://github.com/dheeraj00001/se-mini-project/blob/main/src/schemas/verification.py): `src/schemas/verification.py`

### Grounding

- [Tiered retrieval](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/adapters.py): `src/retrieval/adapters.py`
- [Dual-index store](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/store.py): `src/retrieval/store.py`
- [Rank fusion](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/fusion.py): `src/retrieval/fusion.py`
- [Knowledge ingest route](https://github.com/dheeraj00001/se-mini-project/blob/main/src/gateway/router.py): `src/gateway/router.py`
- [Document ingestion](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/ingest.py): `src/retrieval/ingest.py`
- [Document parser](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/parser.py): `src/retrieval/parser.py`
- [Text chunker](https://github.com/dheeraj00001/se-mini-project/blob/main/src/retrieval/chunker.py): `src/retrieval/chunker.py`

### Mitigation

- [Mitigation pipeline](https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/pipeline.py): `src/mitigation/pipeline.py`
- [Targeted rewriter](https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/rewriter.py): `src/mitigation/rewriter.py`
- [Local generator](https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/generator.py): `src/mitigation/generator.py`
- [Safety fallback](https://github.com/dheeraj00001/se-mini-project/blob/main/src/mitigation/fallback.py): `src/mitigation/fallback.py`

### Other components

- **Client**
- **Model provider**

## Connections

- Client → React interface: uses (evidence: `README.md`)
- React interface → Verification playground: renders (evidence: `frontend/src/App.tsx`)
- Verification playground → Frontend API client: calls (evidence: `frontend/src/components/Playground.tsx`)
- Frontend API client → API routes: HTTP requests
- Client → FastAPI app: requests (evidence: `README.md`)
- FastAPI app → API routes: registers routes (evidence: `src/gateway/app.py`)
- API routes → Header overrides: parses overrides (evidence: `src/gateway/router.py`)
- API routes → Response buffer: buffers output (evidence: `src/gateway/router.py`)
- API routes → SSE replay: builds stream (evidence: `src/gateway/router.py`)
- API routes → Model provider: proxies generation (evidence: `README.md`)
- API routes → Waterfall verifier: verifies claims (evidence: `src/gateway/router.py`)
- API routes → Document ingestion: ingests documents (evidence: `src/gateway/router.py`)
- Document ingestion → Document parser: extracts text (evidence: `src/retrieval/ingest.py`)
- Document ingestion → Text chunker: chunks text (evidence: `src/retrieval/ingest.py`)
- Document ingestion → Dual-index store: persists chunks (evidence: `src/retrieval/ingest.py`)
- Waterfall verifier → Claim segmentation: segments claims (evidence: `src/verifier/orchestrator.py`)
- Waterfall verifier → Tiered retrieval: retrieves evidence (evidence: `src/verifier/orchestrator.py`)
- Waterfall verifier → NLI scoring: scores evidence (evidence: `src/verifier/orchestrator.py`)
- Tiered retrieval → Dual-index store: searches indexes (evidence: `src/retrieval/adapters.py`)
- Tiered retrieval → Rank fusion: fuses rankings (evidence: `src/retrieval/adapters.py`)
- Waterfall verifier → Mitigation pipeline: mitigates results (evidence: `src/verifier/orchestrator.py`)
- Mitigation pipeline → Targeted rewriter: rewrites claims (evidence: `src/mitigation/pipeline.py`)
- Targeted rewriter → Local generator: generates correction (evidence: `src/mitigation/rewriter.py`)
- Mitigation pipeline → Safety fallback: falls back (evidence: `src/mitigation/pipeline.py`)
- Client → Knowledge ingest route: submits references (evidence: `README.md`)
- Waterfall verifier → Verification contracts: returns reports (evidence: `src/verifier/orchestrator.py`)
