# vishwashn12/grace architecture

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

- Interactive diagram: https://gitdiagram.com/vishwashn12/grace
- Repository: https://github.com/vishwashn12/grace

## Overview

GRACE is an e-commerce support product combining grounded order/seller assistance with policy and complaint knowledge retrieval, plus operational and seller analytics. The main workflow takes a customer query through the chat API into the RAG orchestrator, which selects agent or retrieval-based answering and returns a grounded response; the frontend also exposes dashboard, seller, and insights views. Some backend and page implementations were not sampled, so those relationships are included only where the README or source index supports them.

Main entry points: [`frontend/src/App.jsx`](https://github.com/vishwashn12/grace/blob/main/frontend/src/App.jsx) (Web application), [`backend/core/rag_system.py`](https://github.com/vishwashn12/grace/blob/main/backend/core/rag_system.py) (Answer orchestrator), [`backend/retrievers/hybrid_retriever.py`](https://github.com/vishwashn12/grace/blob/main/backend/retrievers/hybrid_retriever.py) (Hybrid retrieval), [`frontend/src/pages/Chat.jsx`](https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Chat.jsx) (Support chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Support interface"]
  node_frontend["Web application<br/>[App.jsx]"]
  node_chatpage["Support chat<br/>[Chat.jsx]"]
  node_dashboard["Operations dashboard<br/>[Operations.jsx]"]
  node_sellerpage["Seller analytics<br/>[Sellers.jsx]"]
  node_insightspage["Support insights<br/>[InsightsPage.jsx]"]
end

subgraph group_api["API and orchestration"]
  node_chatroute["Chat endpoint<br/>[chat.py]"]
  node_ragclient["RAG client<br/>[rag_client.py]"]
  node_rag["Answer orchestrator<br/>[rag_system.py]"]
end

subgraph group_agent["Agent support"]
  node_agentgraph["Agent graph<br/>[graph.py]"]
  node_agentnodes["Agent nodes<br/>[nodes.py]"]
  node_tools["Support tools<br/>[tools.py]"]
end

subgraph group_retrieval["Knowledge retrieval"]
  node_hybrid["Hybrid retrieval"]
  node_faiss[("FAISS search<br/>[faiss_retriever.py]")]
  node_bm25[("BM25 index<br/>[bm25_builder.py]")]
  node_ragstages["RAG query stages"]
end

subgraph group_analytics["Business analytics"]
  node_analyticsroute["Analytics endpoint<br/>[analytics.py]"]
  node_operations["Operations metrics"]
  node_insightsroute["Insights endpoint<br/>[insights.py]"]
  node_seller["Seller KPI service<br/>[seller_service.py]"]
  node_data["Dataset loader<br/>[data_service.py]"]
end

node_customer(("Customer"))

node_customer -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_chatpage
node_frontend -->|"routes to"| node_dashboard
node_frontend -->|"routes to"| node_sellerpage
node_frontend -->|"routes to"| node_insightspage
node_chatpage -.->|"submits queries"| node_chatroute
node_chatroute -->|"calls"| node_ragclient
node_ragclient -->|"invokes"| node_rag
node_rag -.->|"dispatches agent path"| node_agentgraph
node_rag -.->|"retrieves documents"| node_hybrid
node_agentgraph -->|"uses nodes"| node_agentnodes
node_agentnodes -->|"executes tool calls"| node_tools
node_hybrid -->|"dense search"| node_faiss
node_hybrid -->|"sparse search"| node_bm25
node_rag -->|"uses query stages"| node_ragstages
node_dashboard -.->|"requests metrics"| node_analyticsroute
node_analyticsroute -->|"calls"| node_operations
node_operations -->|"loads data"| node_data
node_sellerpage -.->|"requests seller data"| node_insightsroute
node_insightsroute -->|"calls"| node_seller
node_seller -->|"loads data"| node_data

click node_frontend "https://github.com/vishwashn12/grace/blob/main/frontend/src/App.jsx"
click node_chatpage "https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Chat.jsx"
click node_dashboard "https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Operations.jsx"
click node_sellerpage "https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Sellers.jsx"
click node_insightspage "https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/InsightsPage.jsx"
click node_chatroute "https://github.com/vishwashn12/grace/blob/main/backend/routes/chat.py"
click node_ragclient "https://github.com/vishwashn12/grace/blob/main/backend/services/rag_client.py"
click node_rag "https://github.com/vishwashn12/grace/blob/main/backend/core/rag_system.py"
click node_agentgraph "https://github.com/vishwashn12/grace/blob/main/backend/agent/graph.py"
click node_agentnodes "https://github.com/vishwashn12/grace/blob/main/backend/agent/nodes.py"
click node_tools "https://github.com/vishwashn12/grace/blob/main/backend/agent/tools.py"
click node_hybrid "https://github.com/vishwashn12/grace/blob/main/backend/retrievers/hybrid_retriever.py"
click node_faiss "https://github.com/vishwashn12/grace/blob/main/backend/retrievers/faiss_retriever.py"
click node_bm25 "https://github.com/vishwashn12/grace/blob/main/backend/retrievers/bm25_builder.py"
click node_ragstages "https://github.com/vishwashn12/grace/tree/main/backend/rag"
click node_analyticsroute "https://github.com/vishwashn12/grace/blob/main/backend/routes/analytics.py"
click node_operations "https://github.com/vishwashn12/grace/blob/main/backend/services/operations_service.py"
click node_insightsroute "https://github.com/vishwashn12/grace/blob/main/backend/routes/insights.py"
click node_seller "https://github.com/vishwashn12/grace/blob/main/backend/services/seller_service.py"
click node_data "https://github.com/vishwashn12/grace/blob/main/backend/services/data_service.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_chatpage,node_dashboard,node_sellerpage,node_insightspage toneBlue
class node_chatroute,node_ragclient,node_rag toneAmber
class node_agentgraph,node_agentnodes,node_tools toneMint
class node_hybrid,node_faiss,node_bm25,node_ragstages toneRose
class node_analyticsroute,node_operations,node_insightsroute,node_seller,node_data,node_customer toneIndigo
```

## Components

### Support interface

- [Web application](https://github.com/vishwashn12/grace/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Support chat](https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Operations dashboard](https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Operations.jsx): `frontend/src/pages/Operations.jsx`
- [Seller analytics](https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/Sellers.jsx): `frontend/src/pages/Sellers.jsx`
- [Support insights](https://github.com/vishwashn12/grace/blob/main/frontend/src/pages/InsightsPage.jsx): `frontend/src/pages/InsightsPage.jsx`

### API and orchestration

- [Chat endpoint](https://github.com/vishwashn12/grace/blob/main/backend/routes/chat.py): `backend/routes/chat.py`
- [RAG client](https://github.com/vishwashn12/grace/blob/main/backend/services/rag_client.py): `backend/services/rag_client.py`
- [Answer orchestrator](https://github.com/vishwashn12/grace/blob/main/backend/core/rag_system.py): `backend/core/rag_system.py`

### Agent support

- [Agent graph](https://github.com/vishwashn12/grace/blob/main/backend/agent/graph.py): `backend/agent/graph.py`
- [Agent nodes](https://github.com/vishwashn12/grace/blob/main/backend/agent/nodes.py): `backend/agent/nodes.py`
- [Support tools](https://github.com/vishwashn12/grace/blob/main/backend/agent/tools.py): `backend/agent/tools.py`

### Knowledge retrieval

- [Hybrid retrieval](https://github.com/vishwashn12/grace/blob/main/backend/retrievers/hybrid_retriever.py): `backend/retrievers/hybrid_retriever.py`
- [FAISS search](https://github.com/vishwashn12/grace/blob/main/backend/retrievers/faiss_retriever.py): `backend/retrievers/faiss_retriever.py`
- [BM25 index](https://github.com/vishwashn12/grace/blob/main/backend/retrievers/bm25_builder.py): `backend/retrievers/bm25_builder.py`
- [RAG query stages](https://github.com/vishwashn12/grace/tree/main/backend/rag): `backend/rag`

### Business analytics

- [Analytics endpoint](https://github.com/vishwashn12/grace/blob/main/backend/routes/analytics.py): `backend/routes/analytics.py`
- [Operations metrics](https://github.com/vishwashn12/grace/blob/main/backend/services/operations_service.py): `backend/services/operations_service.py`
- [Insights endpoint](https://github.com/vishwashn12/grace/blob/main/backend/routes/insights.py): `backend/routes/insights.py`
- [Seller KPI service](https://github.com/vishwashn12/grace/blob/main/backend/services/seller_service.py): `backend/services/seller_service.py`
- [Dataset loader](https://github.com/vishwashn12/grace/blob/main/backend/services/data_service.py): `backend/services/data_service.py`

### Other components

- **Customer**

## Connections

- Customer → Web application: uses
- Web application → Support chat: routes to (evidence: `frontend/src/App.jsx`)
- Web application → Operations dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Web application → Seller analytics: routes to (evidence: `frontend/src/App.jsx`)
- Web application → Support insights: routes to (evidence: `frontend/src/App.jsx`)
- Support chat → Chat endpoint: submits queries
- Chat endpoint → RAG client: calls (evidence: `backend/routes/chat.py`)
- RAG client → Answer orchestrator: invokes (evidence: `backend/services/rag_client.py`)
- Answer orchestrator → Agent graph: dispatches agent path
- Answer orchestrator → Hybrid retrieval: retrieves documents
- Agent graph → Agent nodes: uses nodes (evidence: `backend/agent/graph.py`)
- Agent nodes → Support tools: executes tool calls (evidence: `backend/agent/nodes.py`)
- Hybrid retrieval → FAISS search: dense search (evidence: `backend/retrievers/hybrid_retriever.py`)
- Hybrid retrieval → BM25 index: sparse search (evidence: `backend/retrievers/hybrid_retriever.py`)
- Answer orchestrator → RAG query stages: uses query stages (evidence: `backend/core/rag_system.py`)
- Operations dashboard → Analytics endpoint: requests metrics
- Analytics endpoint → Operations metrics: calls (evidence: `backend/routes/analytics.py`)
- Operations metrics → Dataset loader: loads data (evidence: `backend/services/operations_service.py`)
- Seller analytics → Insights endpoint: requests seller data
- Insights endpoint → Seller KPI service: calls (evidence: `backend/routes/insights.py`)
- Seller KPI service → Dataset loader: loads data (evidence: `backend/services/seller_service.py`)
