# piyush30007/nexa-ai architecture

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

- Interactive diagram: https://gitdiagram.com/piyush30007/nexa-ai
- Repository: https://github.com/piyush30007/nexa-ai

## Overview

Nexa AI is an enterprise policy assistant combining a React client, authenticated FastAPI endpoints, document ingestion, and an agentic RAG workflow. Users upload knowledge-base documents, then ask questions; the agent plans retrieval, evaluates evidence, and returns grounded answers with sources. The product also supports conversation history, usage reporting, and evaluation. The README documents several guardrail and infrastructure behaviors beyond the sampled implementation; those links are cited to the README. The tree and excerpts also show an older, separate RAG API, which is represented without assuming it participates in the current agent workflow.

Main entry points: [`backend/app/main.py`](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/main.py) (Enterprise API), [`backend/app/ingestion/processor.py`](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/processor.py) (Document Ingestion), [`backend/app/agents/graph.py`](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/graph.py) (Agent State Graph), [`frontend/src/api/client.js`](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/api/client.js) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Experience"]
  node_web["React Application<br/>[App.jsx]"]
  node_assistant["Assistant Chat<br/>[AIAssistant.jsx]"]
  node_knowledge_ui["Knowledge Base UI<br/>[KnowledgeBase.jsx]"]
  node_api_client["API Client<br/>[client.js]"]
  node_eval_ui["Evaluation UI<br/>[Evaluation.jsx]"]
  node_usage_ui["Usage Dashboard<br/>[Usage.jsx]"]
end

subgraph group_api["API and Identity"]
  node_ingress["Enterprise API<br/>[main.py]"]
  node_auth["Clerk Authentication<br/>[clerk_auth.py]"]
end

subgraph group_knowledge["Knowledge and Retrieval"]
  node_ingestion["Document Ingestion<br/>[processor.py]"]
  node_loaders["Format Loaders"]
  node_cleaner["Text Cleaning<br/>[cleaner.py]"]
  node_splitter["Chunking<br/>[splitter.py]"]
  node_embedding["Embedding Service<br/>[embedding.py]"]
  node_qdrant[("Qdrant Store<br/>[qdrant_service.py]")]
  node_hybrid["Hybrid Retrieval<br/>[hybrid_service.py]"]
  node_ranking["Result Reranking"]
  node_legacy_rag["Legacy RAG API<br/>[rag.py]"]
end

subgraph group_agent["Agent and Safety"]
  node_graph["Agent State Graph<br/>[graph.py]"]
  node_planner["Query Planner<br/>[planner.py]"]
  node_retriever["Agent Retriever<br/>[retriever.py]"]
  node_sufficiency["Evidence Evaluator<br/>[sufficiency.py]"]
  node_responder["Answer Responder<br/>[responder.py]"]
  node_guardrails["Guardrails"]
  node_gateway["Model Gateway<br/>[client.py]"]
end

subgraph group_persistence["Persistence and Services"]
  node_conversation["Conversation Service"]
  node_db[("PostgreSQL Models<br/>[database.py]")]
  node_cache[("Embedding and Response Cache<br/>[cache.py]")]
  node_evaluation["Evaluation Service<br/>[evaluation.py]"]
end

node_user(("User"))
node_portkey{{"Portkey AI Gateway"}}
node_gemini{{"Gemini Embeddings"}}

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_assistant
node_web -->|"routes to"| node_knowledge_ui
node_assistant -->|"requests"| node_api_client
node_knowledge_ui -->|"requests"| node_api_client
node_api_client -->|"calls endpoints"| node_ingress
node_ingress -->|"authenticates"| node_auth
node_ingress -->|"applies"| node_guardrails
node_ingress -->|"invokes"| node_graph
node_ingress -->|"persists turns"| node_conversation
node_conversation -->|"reads and writes"| node_db
node_ingress -->|"uploads documents"| node_ingestion
node_ingestion -->|"extracts formats"| node_loaders
node_ingestion -->|"cleans text"| node_cleaner
node_ingestion -->|"chunks text"| node_splitter
node_ingestion -->|"embeds chunks"| node_embedding
node_embedding -->|"checks cache"| node_cache
node_embedding -->|"embeds text"| node_gemini
node_graph -->|"dispatches"| node_planner
node_graph -->|"dispatches"| node_retriever
node_graph -->|"dispatches"| node_sufficiency
node_graph -->|"dispatches"| node_responder
node_planner -->|"routes retrieval"| node_retriever
node_planner -->|"routes conversation"| node_responder
node_retriever -->|"searches"| node_hybrid
node_hybrid -->|"queries vectors"| node_qdrant
node_hybrid -->|"reranks candidates"| node_ranking
node_retriever -->|"submits evidence"| node_sufficiency
node_sufficiency -->|"retries query"| node_planner
node_sufficiency -->|"routes answer"| node_responder
node_responder -->|"generates answer"| node_gateway
node_gateway -->|"routes inference"| node_portkey
node_ingress -->|"runs evaluation"| node_evaluation
node_eval_ui -->|"requests evaluation"| node_api_client
node_usage_ui -->|"requests usage"| node_api_client
node_legacy_rag -->|"reads and writes"| node_db

click node_web "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/App.jsx"
click node_assistant "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/AIAssistant.jsx"
click node_knowledge_ui "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/KnowledgeBase.jsx"
click node_api_client "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/api/client.js"
click node_ingress "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/main.py"
click node_auth "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/auth/clerk_auth.py"
click node_conversation "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/conversation_service.py"
click node_db "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/database.py"
click node_ingestion "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/processor.py"
click node_loaders "https://github.com/piyush30007/nexa-ai/tree/enterprise-v2/backend/app/ingestion/Loader"
click node_cleaner "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/Preprocessing/cleaner.py"
click node_splitter "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/Chunking/splitter.py"
click node_embedding "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/embedding.py"
click node_qdrant "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/retrieval/qdrant_service.py"
click node_hybrid "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/retrieval/hybrid_service.py"
click node_ranking "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/retrieval/ranking_services.py"
click node_graph "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/graph.py"
click node_planner "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/planner.py"
click node_retriever "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/retriever.py"
click node_sufficiency "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/sufficiency.py"
click node_responder "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/responder.py"
click node_guardrails "https://github.com/piyush30007/nexa-ai/tree/enterprise-v2/backend/app/guardrails"
click node_gateway "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/gateway/client.py"
click node_cache "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/cache.py"
click node_legacy_rag "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/rag.py"
click node_evaluation "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/evaluation.py"
click node_eval_ui "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/Evaluation.jsx"
click node_usage_ui "https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/Usage.jsx"

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_web,node_assistant,node_knowledge_ui,node_api_client,node_eval_ui,node_usage_ui,node_user toneBlue
class node_ingress,node_auth toneAmber
class node_ingestion,node_loaders,node_cleaner,node_splitter,node_embedding,node_qdrant,node_hybrid,node_ranking,node_legacy_rag toneMint
class node_graph,node_planner,node_retriever,node_sufficiency,node_responder,node_guardrails,node_gateway toneRose
class node_conversation,node_db,node_cache,node_evaluation,node_portkey,node_gemini toneIndigo
```

## Components

### User Experience

- [React Application](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Assistant Chat](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/AIAssistant.jsx): `frontend/src/pages/AIAssistant.jsx`
- [Knowledge Base UI](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/KnowledgeBase.jsx): `frontend/src/pages/KnowledgeBase.jsx`
- [API Client](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Evaluation UI](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/Evaluation.jsx): `frontend/src/pages/Evaluation.jsx`
- [Usage Dashboard](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/frontend/src/pages/Usage.jsx): `frontend/src/pages/Usage.jsx`

### API and Identity

- [Enterprise API](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/main.py): `backend/app/main.py`
- [Clerk Authentication](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/auth/clerk_auth.py): `backend/app/auth/clerk_auth.py`

### Knowledge and Retrieval

- [Document Ingestion](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/processor.py): `backend/app/ingestion/processor.py`
- [Format Loaders](https://github.com/piyush30007/nexa-ai/tree/enterprise-v2/backend/app/ingestion/Loader): `backend/app/ingestion/Loader`
- [Text Cleaning](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/Preprocessing/cleaner.py): `backend/app/ingestion/Preprocessing/cleaner.py`
- [Chunking](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/ingestion/Chunking/splitter.py): `backend/app/ingestion/Chunking/splitter.py`
- [Embedding Service](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/embedding.py): `backend/app/services/embedding.py`
- [Qdrant Store](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/retrieval/qdrant_service.py): `backend/app/services/retrieval/qdrant_service.py`
- [Hybrid Retrieval](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/retrieval/hybrid_service.py): `backend/app/services/retrieval/hybrid_service.py`
- [Result Reranking](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/retrieval/ranking_services.py): `backend/app/services/retrieval/ranking_services.py`
- [Legacy RAG API](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/rag.py): `backend/rag.py`

### Agent and Safety

- [Agent State Graph](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Query Planner](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/planner.py): `backend/app/agents/nodes/planner.py`
- [Agent Retriever](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/retriever.py): `backend/app/agents/nodes/retriever.py`
- [Evidence Evaluator](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/sufficiency.py): `backend/app/agents/nodes/sufficiency.py`
- [Answer Responder](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/agents/nodes/responder.py): `backend/app/agents/nodes/responder.py`
- [Guardrails](https://github.com/piyush30007/nexa-ai/tree/enterprise-v2/backend/app/guardrails): `backend/app/guardrails`
- [Model Gateway](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/gateway/client.py): `backend/app/gateway/client.py`

### Persistence and Services

- [Conversation Service](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/conversation_service.py): `backend/app/services/conversation_service.py`
- [PostgreSQL Models](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/database.py): `backend/database.py`
- [Embedding and Response Cache](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/app/services/cache.py): `backend/app/services/cache.py`
- [Evaluation Service](https://github.com/piyush30007/nexa-ai/blob/enterprise-v2/backend/evaluation.py): `backend/evaluation.py`

### Other components

- **User**
- **Portkey AI Gateway**
- **Gemini Embeddings**

## Connections

- User → React Application: uses
- React Application → Assistant Chat: routes to (evidence: `frontend/src/App.jsx`)
- React Application → Knowledge Base UI: routes to (evidence: `frontend/src/App.jsx`)
- Assistant Chat → API Client: requests (evidence: `frontend/src/pages/AIAssistant.jsx`)
- Knowledge Base UI → API Client: requests (evidence: `frontend/src/api/client.js`)
- API Client → Enterprise API: calls endpoints (evidence: `frontend/src/api/client.js`)
- Enterprise API → Clerk Authentication: authenticates (evidence: `backend/app/main.py`)
- Enterprise API → Guardrails: applies (evidence: `backend/app/main.py`)
- Enterprise API → Agent State Graph: invokes (evidence: `backend/app/main.py`)
- Enterprise API → Conversation Service: persists turns (evidence: `backend/app/main.py`)
- Conversation Service → PostgreSQL Models: reads and writes (evidence: `backend/app/services/conversation_service.py`)
- Enterprise API → Document Ingestion: uploads documents (evidence: `backend/app/main.py`)
- Document Ingestion → Format Loaders: extracts formats (evidence: `backend/app/ingestion/processor.py`)
- Document Ingestion → Text Cleaning: cleans text (evidence: `backend/app/ingestion/processor.py`)
- Document Ingestion → Chunking: chunks text (evidence: `backend/app/ingestion/processor.py`)
- Document Ingestion → Embedding Service: embeds chunks (evidence: `backend/app/ingestion/processor.py`)
- Embedding Service → Embedding and Response Cache: checks cache (evidence: `backend/app/services/embedding.py`)
- Embedding Service → Gemini Embeddings: embeds text
- Agent State Graph → Query Planner: dispatches (evidence: `backend/app/agents/graph.py`)
- Agent State Graph → Agent Retriever: dispatches (evidence: `backend/app/agents/graph.py`)
- Agent State Graph → Evidence Evaluator: dispatches (evidence: `backend/app/agents/graph.py`)
- Agent State Graph → Answer Responder: dispatches (evidence: `backend/app/agents/graph.py`)
- Query Planner → Agent Retriever: routes retrieval
- Query Planner → Answer Responder: routes conversation
- Agent Retriever → Hybrid Retrieval: searches (evidence: `backend/app/agents/nodes/retriever.py`)
- Hybrid Retrieval → Qdrant Store: queries vectors (evidence: `backend/app/services/retrieval/hybrid_service.py`)
- Hybrid Retrieval → Result Reranking: reranks candidates
- Agent Retriever → Evidence Evaluator: submits evidence
- Evidence Evaluator → Query Planner: retries query
- Evidence Evaluator → Answer Responder: routes answer
- Answer Responder → Model Gateway: generates answer
- Model Gateway → Portkey AI Gateway: routes inference
- Enterprise API → Evaluation Service: runs evaluation (evidence: `backend/app/main.py`)
- Evaluation UI → API Client: requests evaluation (evidence: `frontend/src/pages/Evaluation.jsx`)
- Usage Dashboard → API Client: requests usage
- Legacy RAG API → PostgreSQL Models: reads and writes (evidence: `backend/rag.py`)
