# piyushjha0409/quickart architecture

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

- Interactive diagram: https://gitdiagram.com/piyushjha0409/quickart
- Repository: https://github.com/piyushjha0409/quickart

## Overview

QuickCart is a customer-support agent for quick-commerce orders, delivery issues, refunds, disputes, and policy questions. A customer uses the chat UI and API; the server supplies demo customer context and invokes a LangGraph agent, which chooses model responses and tools. Tools read order data, retrieve policy, and record actions; gated work enters a human review queue. PostgreSQL holds operational and knowledge-base data. The README also describes evaluation and production-monitoring goals, but no corresponding runtime subsystem appears in the provided tree. Edges reflect shown calls or documented relationships; unsampled subsystems are not inferred.

Main entry points: [`src/quickcart/server.py`](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/server.py) (HTTP API), [`src/quickcart/node.py`](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/node.py) (LLM and tools), [`src/quickcart/tools.py`](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/tools.py) (Order and action tools), [`src/quickcart/main.py`](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/main.py) (Agent workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Customer interface"]
  node_web_ui["Chat UI<br/>[app.js]"]
  node_api["HTTP API<br/>[server.py]"]
end

subgraph group_agent["Agent runtime"]
  node_workflow["Agent workflow<br/>[main.py]"]
  node_agent_node["LLM and tools<br/>[node.py]"]
  node_prompt["Support policy prompt<br/>[prompts.py]"]
  node_model["Model selection<br/>[models.py]"]
end

subgraph group_support["Support capabilities"]
  node_tool_registry["Tool registry<br/>[init.py]"]
  node_order_tools["Order and action tools<br/>[tools.py]"]
  node_kb_search["Policy retrieval<br/>[knowledge.py]"]
  node_review_queue["Human review<br/>[reviews.py]"]
end

subgraph group_data["Data and policy"]
  node_postgres[("PostgreSQL")]
  node_schema["Data models<br/>[models.py]"]
  node_db_setup["Database setup<br/>[init.py]"]
  node_seed_data["Demo data<br/>[seed.py]"]
  node_kb_ingest["Knowledge ingestion<br/>[ingest_kb.py]"]
  node_kb_pages["Policy pages"]
end

node_customer(("Customer"))
node_llm_service{{"OpenAI models"}}

node_customer -->|"starts chat"| node_web_ui
node_web_ui -->|"sends chat"| node_api
node_api -->|"invokes"| node_workflow
node_api -->|"selects effort"| node_model
node_api -->|"routes review"| node_review_queue
node_api -->|"creates tables"| node_db_setup
node_workflow -->|"runs nodes"| node_agent_node
node_workflow -->|"uses demo user"| node_seed_data
node_workflow -->|"loads context"| node_order_tools
node_agent_node -->|"builds prompt"| node_prompt
node_agent_node -->|"selects model"| node_model
node_agent_node -->|"runs tools"| node_tool_registry
node_agent_node -->|"escalates"| node_order_tools
node_model -->|"calls"| node_llm_service
node_tool_registry -->|"registers"| node_kb_search
node_tool_registry -->|"registers"| node_order_tools
node_order_tools -->|"reads and writes"| node_postgres
node_order_tools -->|"notifies"| node_review_queue
node_kb_search -->|"searches vectors"| node_postgres
node_review_queue -->|"reads and updates"| node_postgres
node_db_setup -->|"creates tables"| node_schema
node_db_setup -->|"connects"| node_postgres
node_seed_data -->|"creates records"| node_schema
node_kb_ingest -->|"stores chunks"| node_postgres

click node_web_ui "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/web/app.js"
click node_api "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/server.py"
click node_workflow "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/main.py"
click node_agent_node "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/node.py"
click node_prompt "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/prompts.py"
click node_model "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/models.py"
click node_tool_registry "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/init.py"
click node_order_tools "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/tools.py"
click node_kb_search "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/knowledge.py"
click node_review_queue "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/reviews.py"
click node_schema "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/db/models.py"
click node_db_setup "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/db/init.py"
click node_seed_data "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/db/seed.py"
click node_kb_ingest "https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/ingest_kb.py"
click node_kb_pages "https://github.com/piyushjha0409/quickart/tree/main/kb"

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_ui,node_api toneBlue
class node_workflow,node_agent_node,node_prompt,node_model toneAmber
class node_tool_registry,node_order_tools,node_kb_search,node_review_queue toneMint
class node_postgres,node_schema,node_db_setup,node_seed_data,node_kb_ingest,node_kb_pages toneRose
class node_customer,node_llm_service toneIndigo
```

## Components

### Customer interface

- [Chat UI](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/web/app.js): `src/quickcart/web/app.js`
- [HTTP API](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/server.py): `src/quickcart/server.py`

### Agent runtime

- [Agent workflow](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/main.py): `src/quickcart/main.py`
- [LLM and tools](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/node.py): `src/quickcart/node.py`
- [Support policy prompt](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/prompts.py): `src/quickcart/prompts.py`
- [Model selection](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/models.py): `src/quickcart/models.py`

### Support capabilities

- [Tool registry](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/init.py): `src/quickcart/init.py`
- [Order and action tools](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/tools.py): `src/quickcart/tools.py`
- [Policy retrieval](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/knowledge.py): `src/quickcart/knowledge.py`
- [Human review](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/reviews.py): `src/quickcart/reviews.py`

### Data and policy

- **PostgreSQL**
- [Data models](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/db/models.py): `src/quickcart/db/models.py`
- [Database setup](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/db/init.py): `src/quickcart/db/init.py`
- [Demo data](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/db/seed.py): `src/quickcart/db/seed.py`
- [Knowledge ingestion](https://github.com/piyushjha0409/quickart/blob/main/src/quickcart/ingest_kb.py): `src/quickcart/ingest_kb.py`
- [Policy pages](https://github.com/piyushjha0409/quickart/tree/main/kb): `kb`

### Other components

- **Customer**
- **OpenAI models**

## Connections

- Customer → Chat UI: starts chat (evidence: `README.md`)
- Chat UI → HTTP API: sends chat (evidence: `README.md`)
- HTTP API → Agent workflow: invokes (evidence: `src/quickcart/server.py`)
- HTTP API → Model selection: selects effort (evidence: `src/quickcart/server.py`)
- HTTP API → Human review: routes review (evidence: `src/quickcart/server.py`)
- HTTP API → Database setup: creates tables (evidence: `src/quickcart/server.py`)
- Agent workflow → LLM and tools: runs nodes (evidence: `src/quickcart/main.py`)
- Agent workflow → Demo data: uses demo user (evidence: `src/quickcart/main.py`)
- Agent workflow → Order and action tools: loads context (evidence: `src/quickcart/main.py`)
- LLM and tools → Support policy prompt: builds prompt (evidence: `src/quickcart/node.py`)
- LLM and tools → Model selection: selects model (evidence: `src/quickcart/node.py`)
- LLM and tools → Tool registry: runs tools (evidence: `src/quickcart/node.py`)
- LLM and tools → Order and action tools: escalates (evidence: `src/quickcart/node.py`)
- Model selection → OpenAI models: calls (evidence: `src/quickcart/models.py`)
- Tool registry → Policy retrieval: registers (evidence: `src/quickcart/init.py`)
- Tool registry → Order and action tools: registers (evidence: `src/quickcart/init.py`)
- Order and action tools → PostgreSQL: reads and writes (evidence: `src/quickcart/tools.py`)
- Order and action tools → Human review: notifies (evidence: `src/quickcart/tools.py`)
- Policy retrieval → PostgreSQL: searches vectors (evidence: `src/quickcart/knowledge.py`)
- Human review → PostgreSQL: reads and updates (evidence: `src/quickcart/reviews.py`)
- Database setup → Data models: creates tables (evidence: `src/quickcart/db/init.py`)
- Database setup → PostgreSQL: connects (evidence: `src/quickcart/db/init.py`)
- Demo data → Data models: creates records (evidence: `src/quickcart/db/seed.py`)
- Knowledge ingestion → PostgreSQL: stores chunks (evidence: `src/quickcart/ingest_kb.py`)