# kirtipratihar/yap-engine-v2-agentic-self-correcting-rag architecture

> Architecture diagram of the GitHub repository kirtipratihar/yap-engine-v2-agentic-self-correcting-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag
- Repository: https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag

## Overview

Yap Engine is a multi-user document Q&A assistant. Users authenticate in the Next.js chat, upload PDFs or images, then ask questions and receive document-grounded answers with citations and quality metadata. The backend handles ingestion and session-scoped retrieval, while a LangGraph workflow routes intents, evaluates retrieved chunks, retries weak searches, and generates answers. The graph captures documented capabilities as well as sampled calls; several backend details, including streaming and observability implementation, are documented but not shown in the excerpts.

Main entry points: [`backend/main.py`](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py) (API and sessions), [`backend/graph.py`](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/graph.py) (RAG orchestration), [`frontend/src/app/page.js`](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/frontend/src/app/page.js) (Chat and upload UI), [`frontend/src/app/api/proxy/[...slug]/route.js`](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/frontend/src/app/api/proxy/%5B...slug%5D/route.js) (Backend proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat client"]
  node_chat["Chat and upload UI<br/>[page.js]"]
  node_proxy["Backend proxy<br/>[route.js]"]
end

subgraph group_api["Backend API"]
  node_api_main["API and sessions<br/>[main.py]"]
  node_auth["Authentication and quotas<br/>[main.py]"]
  node_session_memory[("Session memory<br/>[main.py]")]
  node_quality_metrics["Quality and health endpoints<br/>[main.py]"]
end

subgraph group_ingest["Document ingestion"]
  node_ingest_flow["Upload processing<br/>[main.py]"]
  node_document_extract["Extract and chunk<br/>[main.py]"]
  node_embed["Text embeddings<br/>[main.py]"]
end

subgraph group_rag["RAG workflow"]
  node_rag_graph["RAG orchestration<br/>[graph.py]"]
  node_intent_router["Intent classifier<br/>[router.py]"]
  node_retrieval["Hybrid retrieval<br/>[main.py]"]
  node_evaluation["Retrieval evaluation<br/>[evaluator.py]"]
  node_rewrite["Query rewrite<br/>[evaluator.py]"]
  node_answer["Answer generation<br/>[graph.py]"]
end

subgraph group_services["External services"]
  node_vector_store[("Document vectors")]
  node_llm{{"Groq LLM"}}
end

node_user(("Research user"))

node_user -->|"asks and uploads"| node_chat
node_chat -->|"sends requests"| node_api_main
node_chat -.->|"can route through"| node_proxy
node_proxy -->|"forwards requests"| node_api_main
node_api_main -->|"authenticates users"| node_auth
node_api_main -->|"handles uploads"| node_ingest_flow
node_ingest_flow -->|"extracts and chunks"| node_document_extract
node_document_extract -->|"embeds chunks"| node_embed
node_embed -->|"writes vectors"| node_vector_store
node_api_main -->|"invokes graph"| node_rag_graph
node_rag_graph -->|"classifies intent"| node_intent_router
node_rag_graph -->|"requests retrieval"| node_retrieval
node_retrieval -->|"queries vectors"| node_vector_store
node_rag_graph -->|"scores chunks"| node_evaluation
node_rag_graph -->|"rewrites weak queries"| node_rewrite
node_rag_graph -->|"dispatches answer"| node_answer
node_answer -->|"generates answer"| node_llm
node_api_main -->|"keeps session memory"| node_session_memory
node_api_main -->|"records and serves metrics"| node_quality_metrics
node_api_main -->|"returns answer and citations"| node_chat

click node_chat "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/frontend/src/app/page.js"
click node_proxy "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/frontend/src/app/api/proxy/%5B...slug%5D/route.js"
click node_api_main "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_auth "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_ingest_flow "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_document_extract "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_embed "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_rag_graph "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/graph.py"
click node_intent_router "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/router.py"
click node_retrieval "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_evaluation "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/evaluator.py"
click node_rewrite "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/evaluator.py"
click node_answer "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/graph.py"
click node_session_memory "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py"
click node_quality_metrics "https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.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_chat,node_proxy,node_user toneBlue
class node_api_main,node_auth,node_session_memory,node_quality_metrics toneAmber
class node_ingest_flow,node_document_extract,node_embed toneMint
class node_rag_graph,node_intent_router,node_retrieval,node_evaluation,node_rewrite,node_answer toneRose
class node_vector_store,node_llm toneIndigo
```

## Components

### Chat client

- [Chat and upload UI](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/frontend/src/app/page.js): `frontend/src/app/page.js`
- [Backend proxy](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/frontend/src/app/api/proxy/%5B...slug%5D/route.js): `frontend/src/app/api/proxy/[...slug]/route.js`

### Backend API

- [API and sessions](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`
- [Authentication and quotas](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`
- [Session memory](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`
- [Quality and health endpoints](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`

### Document ingestion

- [Upload processing](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`
- [Extract and chunk](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`
- [Text embeddings](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`

### RAG workflow

- [RAG orchestration](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/graph.py): `backend/graph.py`
- [Intent classifier](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/router.py): `backend/router.py`
- [Hybrid retrieval](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/main.py): `backend/main.py`
- [Retrieval evaluation](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/evaluator.py): `backend/evaluator.py`
- [Query rewrite](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/evaluator.py): `backend/evaluator.py`
- [Answer generation](https://github.com/kirtipratihar/yap-engine-v2-agentic-self-correcting-rag/blob/main/backend/graph.py): `backend/graph.py`

### External services

- **Document vectors**
- **Groq LLM**

### Other components

- **Research user**

## Connections

- Research user → Chat and upload UI: asks and uploads (evidence: `README.md`)
- Chat and upload UI → API and sessions: sends requests (evidence: `README.md`)
- Chat and upload UI → Backend proxy: can route through (evidence: `README.md`)
- Backend proxy → API and sessions: forwards requests (evidence: `frontend/src/app/api/proxy/[...slug]/route.js`)
- API and sessions → Authentication and quotas: authenticates users (evidence: `README.md`)
- API and sessions → Upload processing: handles uploads (evidence: `README.md`)
- Upload processing → Extract and chunk: extracts and chunks (evidence: `README.md`)
- Extract and chunk → Text embeddings: embeds chunks (evidence: `README.md`)
- Text embeddings → Document vectors: writes vectors (evidence: `README.md`)
- API and sessions → RAG orchestration: invokes graph (evidence: `backend/main.py`)
- RAG orchestration → Intent classifier: classifies intent (evidence: `backend/graph.py`)
- RAG orchestration → Hybrid retrieval: requests retrieval (evidence: `backend/graph.py`)
- Hybrid retrieval → Document vectors: queries vectors (evidence: `README.md`)
- RAG orchestration → Retrieval evaluation: scores chunks (evidence: `backend/graph.py`)
- RAG orchestration → Query rewrite: rewrites weak queries (evidence: `backend/graph.py`)
- RAG orchestration → Answer generation: dispatches answer (evidence: `backend/graph.py`)
- Answer generation → Groq LLM: generates answer (evidence: `README.md`)
- API and sessions → Session memory: keeps session memory (evidence: `README.md`)
- API and sessions → Quality and health endpoints: records and serves metrics (evidence: `README.md`)
- API and sessions → Chat and upload UI: returns answer and citations (evidence: `README.md`)
