# piyush-nst/resolveai architecture

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

- Interactive diagram: https://gitdiagram.com/piyush-nst/resolveai
- Repository: https://github.com/piyush-nst/resolveai

## Overview

ResolveAI supports two user-facing flows: a knowledge copilot that retrieves support evidence and returns cited answers, and a resolution agent that handles order actions, approval pauses, and escalation. The graph also preserves the documented ingestion/indexing, mock order system, and evaluation capabilities. Relationships are limited to calls or connections shown in excerpts, the source index, or README; unsampled subsystems are represented at directory level where needed.

Main entry points: [`src/resolveai/retrieval/pipeline.py`](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/pipeline.py) (Retrieval Pipeline), [`src/resolveai/api/main.py`](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/api/main.py) (FastAPI Endpoints), [`src/resolveai/agent/graph.py`](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/graph.py) (Agent Workflow), [`src/resolveai/ingestion/pipeline.py`](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/pipeline.py) (Index Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_webui["Support Web UI<br/>[app.js]"]
  node_api["FastAPI Endpoints<br/>[main.py]"]
end

subgraph group_agent["Resolution Agent"]
  node_agent_graph["Agent Workflow<br/>[graph.py]"]
  node_agent_runtime["Agent Runtime<br/>[runtime.py]"]
  node_agent_tools["Agent Tools<br/>[tools.py]"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_retrieval_service["Retrieval Pipeline<br/>[pipeline.py]"]
  node_semantic["Semantic Search<br/>[semantic.py]"]
  node_bm25["BM25 Search<br/>[bm25.py]"]
  node_hybrid["Hybrid Fusion<br/>[hybrid.py]"]
  node_reranker["Cross-Encoder Reranker<br/>[reranker.py]"]
  node_indexing["Index Builder<br/>[pipeline.py]"]
  node_dataset_loader["Support Data Loader<br/>[loader.py]"]
  node_chunking["Document Chunker<br/>[chunker.py]"]
  node_vector_index[("Embedding and Chroma Index<br/>[vectorstore.py]")]
end

subgraph group_orders["Order Operations"]
  node_orders_client["Order System Client<br/>[client.py]"]
  node_orders_db[("Order Database<br/>[db.py]")]
  node_order_models["Order Records<br/>[models.py]"]
  node_order_seed["Demo Data Seeder<br/>[seed.py]"]
end

subgraph group_platform["Model Services"]
  node_llm_client["Agent LLM Client<br/>[client.py]"]
  node_groq{{"Groq LLM"}}
  node_gemini{{"Gemini Fallback"}}
  node_rag_generation["Grounded Answer Generation<br/>[__init__.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_rag_eval["Retrieval Evaluation<br/>[runner.py]"]
  node_agent_eval["Agent Scenario Evaluation<br/>[runner.py]"]
end

node_customer(("Customer"))

node_customer -->|"uses"| node_webui
node_customer -->|"submits queries"| node_api
node_webui -->|"calls endpoints"| node_api
node_api -->|"runs retrieval"| node_retrieval_service
node_api -->|"generates answer"| node_rag_generation
node_api -->|"runs chat and approvals"| node_agent_runtime
node_agent_runtime -->|"builds workflow"| node_agent_graph
node_agent_graph -->|"interprets requests"| node_llm_client
node_agent_graph -->|"dispatches actions"| node_agent_tools
node_agent_graph -->|"searches knowledge"| node_retrieval_service
node_agent_tools -->|"performs order actions"| node_orders_client
node_agent_runtime -->|"configures persistence"| node_orders_db
node_orders_client -->|"reads and writes"| node_orders_db
node_orders_db -->|"maps records"| node_order_models
node_order_seed -->|"creates demo records"| node_order_models
node_indexing -->|"loads support data"| node_dataset_loader
node_indexing -->|"chunks documents"| node_chunking
node_indexing -->|"embeds and indexes"| node_vector_index
node_retrieval_service -->|"runs semantic search"| node_semantic
node_retrieval_service -->|"runs keyword search"| node_bm25
node_retrieval_service -->|"fuses candidates"| node_hybrid
node_retrieval_service -->|"reranks results"| node_reranker
node_semantic -->|"queries vectors"| node_vector_index
node_llm_client -->|"calls primary model"| node_groq
node_llm_client -->|"fails over"| node_gemini
node_rag_generation -->|"generates response"| node_groq
node_rag_eval -->|"evaluates retrieval"| node_retrieval_service
node_agent_eval -->|"runs scenarios"| node_agent_graph
node_agent_eval -->|"checks order outcomes"| node_orders_client

click node_webui "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/webui/static/app.js"
click node_api "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/api/main.py"
click node_agent_graph "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/graph.py"
click node_agent_runtime "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/runtime.py"
click node_agent_tools "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/tools.py"
click node_retrieval_service "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/pipeline.py"
click node_semantic "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/semantic.py"
click node_bm25 "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/bm25.py"
click node_hybrid "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/hybrid.py"
click node_reranker "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/reranker.py"
click node_indexing "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/pipeline.py"
click node_dataset_loader "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/loader.py"
click node_chunking "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/chunker.py"
click node_vector_index "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/vectorstore.py"
click node_orders_client "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/client.py"
click node_orders_db "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/db.py"
click node_order_models "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/models.py"
click node_order_seed "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/seed.py"
click node_llm_client "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/llm/client.py"
click node_rag_generation "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/generation/__init__.py"
click node_config "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/config.py"
click node_rag_eval "https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/evaluation/runner.py"
click node_agent_eval "https://github.com/piyush-nst/resolveai/blob/main/evals/runner.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_webui,node_api toneBlue
class node_agent_graph,node_agent_runtime,node_agent_tools toneAmber
class node_retrieval_service,node_semantic,node_bm25,node_hybrid,node_reranker,node_indexing,node_dataset_loader,node_chunking,node_vector_index toneMint
class node_orders_client,node_orders_db,node_order_models,node_order_seed toneRose
class node_llm_client,node_groq,node_gemini,node_rag_generation,node_config,node_customer toneIndigo
class node_rag_eval,node_agent_eval toneTeal
```

## Components

### User Interface

- [Support Web UI](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/webui/static/app.js): `src/resolveai/webui/static/app.js`
- [FastAPI Endpoints](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/api/main.py): `src/resolveai/api/main.py`

### Resolution Agent

- [Agent Workflow](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/graph.py): `src/resolveai/agent/graph.py`
- [Agent Runtime](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/runtime.py): `src/resolveai/agent/runtime.py`
- [Agent Tools](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/agent/tools.py): `src/resolveai/agent/tools.py`

### Knowledge Retrieval

- [Retrieval Pipeline](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/pipeline.py): `src/resolveai/retrieval/pipeline.py`
- [Semantic Search](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/semantic.py): `src/resolveai/retrieval/semantic.py`
- [BM25 Search](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/bm25.py): `src/resolveai/retrieval/bm25.py`
- [Hybrid Fusion](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/hybrid.py): `src/resolveai/retrieval/hybrid.py`
- [Cross-Encoder Reranker](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/retrieval/reranker.py): `src/resolveai/retrieval/reranker.py`
- [Index Builder](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/pipeline.py): `src/resolveai/ingestion/pipeline.py`
- [Support Data Loader](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/loader.py): `src/resolveai/ingestion/loader.py`
- [Document Chunker](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/chunker.py): `src/resolveai/ingestion/chunker.py`
- [Embedding and Chroma Index](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/ingestion/vectorstore.py): `src/resolveai/ingestion/vectorstore.py`

### Order Operations

- [Order System Client](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/client.py): `src/resolveai/orders/client.py`
- [Order Database](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/db.py): `src/resolveai/orders/db.py`
- [Order Records](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/models.py): `src/resolveai/orders/models.py`
- [Demo Data Seeder](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/orders/seed.py): `src/resolveai/orders/seed.py`

### Model Services

- [Agent LLM Client](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/llm/client.py): `src/resolveai/llm/client.py`
- **Groq LLM**
- **Gemini Fallback**
- [Grounded Answer Generation](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/generation/__init__.py): `src/resolveai/generation/__init__.py`
- [Configuration](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/config.py): `src/resolveai/config.py`

### Evaluation

- [Retrieval Evaluation](https://github.com/piyush-nst/resolveai/blob/main/src/resolveai/evaluation/runner.py): `src/resolveai/evaluation/runner.py`
- [Agent Scenario Evaluation](https://github.com/piyush-nst/resolveai/blob/main/evals/runner.py): `evals/runner.py`

### Other components

- **Customer**

## Connections

- Customer → Support Web UI: uses
- Customer → FastAPI Endpoints: submits queries
- Support Web UI → FastAPI Endpoints: calls endpoints
- FastAPI Endpoints → Retrieval Pipeline: runs retrieval (evidence: `src/resolveai/api/main.py`)
- FastAPI Endpoints → Grounded Answer Generation: generates answer (evidence: `src/resolveai/api/main.py`)
- FastAPI Endpoints → Agent Runtime: runs chat and approvals (evidence: `src/resolveai/api/main.py`)
- Agent Runtime → Agent Workflow: builds workflow (evidence: `src/resolveai/agent/runtime.py`)
- Agent Workflow → Agent LLM Client: interprets requests (evidence: `src/resolveai/agent/graph.py`)
- Agent Workflow → Agent Tools: dispatches actions (evidence: `src/resolveai/agent/graph.py`)
- Agent Workflow → Retrieval Pipeline: searches knowledge (evidence: `src/resolveai/agent/graph.py`)
- Agent Tools → Order System Client: performs order actions (evidence: `src/resolveai/agent/tools.py`)
- Agent Runtime → Order Database: configures persistence (evidence: `src/resolveai/agent/runtime.py`)
- Order System Client → Order Database: reads and writes (evidence: `src/resolveai/orders/client.py`)
- Order Database → Order Records: maps records (evidence: `src/resolveai/orders/db.py`)
- Demo Data Seeder → Order Records: creates demo records (evidence: `src/resolveai/orders/seed.py`)
- Index Builder → Support Data Loader: loads support data (evidence: `src/resolveai/ingestion/pipeline.py`)
- Index Builder → Document Chunker: chunks documents (evidence: `src/resolveai/ingestion/pipeline.py`)
- Index Builder → Embedding and Chroma Index: embeds and indexes (evidence: `src/resolveai/ingestion/pipeline.py`)
- Retrieval Pipeline → Semantic Search: runs semantic search (evidence: `src/resolveai/retrieval/pipeline.py`)
- Retrieval Pipeline → BM25 Search: runs keyword search (evidence: `src/resolveai/retrieval/pipeline.py`)
- Retrieval Pipeline → Hybrid Fusion: fuses candidates (evidence: `src/resolveai/retrieval/pipeline.py`)
- Retrieval Pipeline → Cross-Encoder Reranker: reranks results (evidence: `src/resolveai/retrieval/pipeline.py`)
- Semantic Search → Embedding and Chroma Index: queries vectors (evidence: `src/resolveai/retrieval/semantic.py`)
- Agent LLM Client → Groq LLM: calls primary model (evidence: `src/resolveai/llm/client.py`)
- Agent LLM Client → Gemini Fallback: fails over (evidence: `src/resolveai/llm/client.py`)
- Grounded Answer Generation → Groq LLM: generates response (evidence: `src/resolveai/generation/__init__.py`)
- Retrieval Evaluation → Retrieval Pipeline: evaluates retrieval (evidence: `src/resolveai/evaluation/runner.py`)
- Agent Scenario Evaluation → Agent Workflow: runs scenarios (evidence: `evals/runner.py`)
- Agent Scenario Evaluation → Order System Client: checks order outcomes (evidence: `evals/runner.py`)