# devanshsharma27/queryflow-ai architecture

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

- Interactive diagram: https://gitdiagram.com/devanshsharma27/queryflow-ai
- Repository: https://github.com/devanshsharma27/queryflow-ai

## Overview

Smart AI Agent is a Streamlit chat application backed by a FastAPI service and a LangGraph agent. Users can upload PDFs to a Pinecone knowledge base, then ask questions; the agent routes requests through RAG, judges whether retrieved context is sufficient, optionally searches the web, and generates an answer with a visible workflow trace. The graph preserves PDF parsing, indexing, and retrieval as distinct stages. Agent internals and some documented capabilities are represented from partial source excerpts and README descriptions; uncertain wiring is omitted.

Main entry points: [`frontend/app.py`](https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/app.py) (Chat App), [`frontend/backend_api.py`](https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/backend_api.py) (Backend Client), [`backend/agent.py`](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py) (Query Router), [`backend/main.py`](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py) (Chat Endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_streamlit["Chat App<br/>[app.py]"]
  node_session["Session State<br/>[session_manager.py]"]
  node_ui["UI Components<br/>[ui_components.py]"]
  node_frontend_api["Backend Client<br/>[backend_api.py]"]
end

subgraph group_service["API Service"]
  node_chat_endpoint["Chat Endpoint<br/>[main.py]"]
  node_upload_endpoint["Upload Endpoint<br/>[main.py]"]
  node_pdf_loader["PDF Extraction<br/>[main.py]"]
  node_trace["Trace Events<br/>[main.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_router["Query Router<br/>[agent.py]"]
  node_rag["RAG Lookup<br/>[agent.py]"]
  node_sufficiency["RAG Judge<br/>[agent.py]"]
  node_web["Web Search<br/>[agent.py]"]
  node_answer["Answer Generator<br/>[agent.py]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_retriever["Vector Retriever<br/>[vectorstore.py]"]
  node_chunker["Text Chunking<br/>[vectorstore.py]"]
  node_embedder["Text Embeddings<br/>[vectorstore.py]"]
  node_pinecone[("Pinecone Index<br/>[vectorstore.py]")]
end

node_user(("User"))
node_groq{{"Groq LLM"}}
node_tavily{{"Tavily Search"}}

node_user -->|"sends query"| node_streamlit
node_streamlit -->|"initializes state"| node_session
node_streamlit -->|"renders controls"| node_ui
node_streamlit -->|"submits chat"| node_frontend_api
node_ui -->|"uploads PDF"| node_frontend_api
node_frontend_api -->|"posts query"| node_chat_endpoint
node_frontend_api -->|"posts file"| node_upload_endpoint
node_chat_endpoint -->|"streams agent"| node_router
node_chat_endpoint -->|"formats events"| node_trace
node_trace -->|"returns trace"| node_frontend_api
node_frontend_api -->|"returns answer"| node_streamlit
node_streamlit -->|"displays trace"| node_ui
node_upload_endpoint -->|"loads PDF"| node_pdf_loader
node_upload_endpoint -->|"indexes text"| node_chunker
node_router -->|"requests route"| node_groq
node_router -->|"dispatches RAG"| node_rag
node_router -->|"dispatches web"| node_web
node_router -->|"dispatches answer"| node_answer
node_rag -->|"retrieves chunks"| node_retriever
node_rag -->|"judges context"| node_sufficiency
node_sufficiency -->|"requests verdict"| node_groq
node_sufficiency -->|"dispatches if lacking"| node_web
node_sufficiency -->|"dispatches if sufficient"| node_answer
node_web -.->|"searches query"| node_tavily
node_web -->|"provides results"| node_answer
node_answer -->|"generates response"| node_groq
node_pdf_loader -->|"provides text"| node_chunker
node_chunker -->|"creates chunks"| node_embedder
node_embedder -->|"indexes vectors"| node_pinecone
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"retrieves vectors"| node_pinecone

click node_streamlit "https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/app.py"
click node_session "https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/session_manager.py"
click node_ui "https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/ui_components.py"
click node_frontend_api "https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/backend_api.py"
click node_chat_endpoint "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py"
click node_upload_endpoint "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py"
click node_pdf_loader "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py"
click node_trace "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py"
click node_router "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py"
click node_rag "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py"
click node_sufficiency "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py"
click node_web "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py"
click node_answer "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py"
click node_retriever "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py"
click node_chunker "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py"
click node_embedder "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py"
click node_pinecone "https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.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_streamlit,node_session,node_ui,node_frontend_api,node_user toneBlue
class node_chat_endpoint,node_upload_endpoint,node_pdf_loader,node_trace toneAmber
class node_router,node_rag,node_sufficiency,node_web,node_answer toneMint
class node_retriever,node_chunker,node_embedder,node_pinecone toneRose
class node_groq,node_tavily toneIndigo
```

## Components

### User Interface

- [Chat App](https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/app.py): `frontend/app.py`
- [Session State](https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/session_manager.py): `frontend/session_manager.py`
- [UI Components](https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/ui_components.py): `frontend/ui_components.py`
- [Backend Client](https://github.com/devanshsharma27/queryflow-ai/blob/main/frontend/backend_api.py): `frontend/backend_api.py`

### API Service

- [Chat Endpoint](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py): `backend/main.py`
- [Upload Endpoint](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py): `backend/main.py`
- [PDF Extraction](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py): `backend/main.py`
- [Trace Events](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/main.py): `backend/main.py`

### Agent Workflow

- [Query Router](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py): `backend/agent.py`
- [RAG Lookup](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py): `backend/agent.py`
- [RAG Judge](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py): `backend/agent.py`
- [Web Search](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py): `backend/agent.py`
- [Answer Generator](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/agent.py): `backend/agent.py`

### Knowledge Base

- [Vector Retriever](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py): `backend/vectorstore.py`
- [Text Chunking](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py): `backend/vectorstore.py`
- [Text Embeddings](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py): `backend/vectorstore.py`
- [Pinecone Index](https://github.com/devanshsharma27/queryflow-ai/blob/main/backend/vectorstore.py): `backend/vectorstore.py`

### Other components

- **User**
- **Groq LLM**
- **Tavily Search**

## Connections

- User → Chat App: sends query
- Chat App → Session State: initializes state
- Chat App → UI Components: renders controls
- Chat App → Backend Client: submits chat
- UI Components → Backend Client: uploads PDF
- Backend Client → Chat Endpoint: posts query
- Backend Client → Upload Endpoint: posts file
- Chat Endpoint → Query Router: streams agent
- Chat Endpoint → Trace Events: formats events
- Trace Events → Backend Client: returns trace
- Backend Client → Chat App: returns answer
- Chat App → UI Components: displays trace
- Upload Endpoint → PDF Extraction: loads PDF
- Upload Endpoint → Text Chunking: indexes text
- Query Router → Groq LLM: requests route
- Query Router → RAG Lookup: dispatches RAG
- Query Router → Web Search: dispatches web
- Query Router → Answer Generator: dispatches answer
- RAG Lookup → Vector Retriever: retrieves chunks
- RAG Lookup → RAG Judge: judges context
- RAG Judge → Groq LLM: requests verdict
- RAG Judge → Web Search: dispatches if lacking
- RAG Judge → Answer Generator: dispatches if sufficient
- Web Search → Tavily Search: searches query
- Web Search → Answer Generator: provides results
- Answer Generator → Groq LLM: generates response
- PDF Extraction → Text Chunking: provides text
- Text Chunking → Text Embeddings: creates chunks
- Text Embeddings → Pinecone Index: indexes vectors
- Vector Retriever → Text Embeddings: embeds query
- Vector Retriever → Pinecone Index: retrieves vectors