# kummethachandrikareddy2006-byte/paypilot-ai architecture

> Architecture diagram of the GitHub repository kummethachandrikareddy2006-byte/paypilot-ai, 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/kummethachandrikareddy2006-byte/paypilot-ai
- Repository: https://github.com/kummethachandrikareddy2006-byte/paypilot-ai

## Overview

PayPilot is a local-first shopping assistant: a shopper enters a natural-language request, receives ranked and explained catalog matches, stages a cart, and explicitly confirms a local test order. The FastAPI application owns the API routes and in-memory cart; recommendation logic and catalog access are separate concerns, while order records persist in SQLite. The README also documents product browsing/comparison, cart management, order lookup, and payment routes. Some source excerpts are partial, so uncertain implementation links are omitted or shown as unverified.

Main entry points: [`backend/main.py`](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py) (FastAPI routes), [`frontend/index.html`](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/frontend/index.html) (Browser UI), [`backend/agent.py`](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/agent.py) (Intent extraction), [`backend/product_engine.py`](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/product_engine.py) (Catalog access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Shopping experience"]
  node_web_ui["Browser UI<br/>[index.html]"]
  node_api["FastAPI routes<br/>[main.py]"]
end

subgraph group_recommendations["Recommendations"]
  node_intent["Intent extraction<br/>[agent.py]"]
  node_ranking["Scoring and explanations<br/>[agent.py]"]
  node_catalog["Catalog access<br/>[product_engine.py]"]
  node_catalog_data["Seeded catalog<br/>[products.csv]"]
end

subgraph group_commerce["Commerce operations"]
  node_cart["Cart operations<br/>[main.py]"]
  node_checkout["Checkout and order placement<br/>[main.py]"]
  node_payment["Test payment result<br/>[payment.py]"]
  node_order_queries["Order lookup and status<br/>[main.py]"]
end

subgraph group_persistence["Local data"]
  node_order_store[("SQLite order store<br/>[db.py]")]
end

node_shopper(("Shopper"))

node_shopper -->|"submits request"| node_web_ui
node_web_ui -->|"calls API"| node_api
node_api -->|"invokes agent"| node_intent
node_intent -->|"scores matches"| node_ranking
node_ranking -->|"searches catalog"| node_catalog_data
node_api -->|"looks up products"| node_catalog
node_catalog -->|"reads CSV"| node_catalog_data
node_api -->|"manages cart"| node_cart
node_shopper -->|"confirms order"| node_checkout
node_api -->|"handles checkout"| node_checkout
node_checkout -->|"saves order"| node_order_store
node_api -->|"serves order routes"| node_order_queries
node_order_queries -->|"reads and updates"| node_order_store
node_api -.->|"uses payment helper"| node_payment

click node_web_ui "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/frontend/index.html"
click node_api "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py"
click node_intent "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/agent.py"
click node_ranking "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/agent.py"
click node_catalog "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/product_engine.py"
click node_catalog_data "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/data/products.csv"
click node_cart "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py"
click node_checkout "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py"
click node_payment "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/payment.py"
click node_order_queries "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py"
click node_order_store "https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/database/db.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_web_ui,node_api toneBlue
class node_intent,node_ranking,node_catalog,node_catalog_data toneAmber
class node_cart,node_checkout,node_payment,node_order_queries toneMint
class node_order_store toneRose
class node_shopper toneIndigo
```

## Components

### Shopping experience

- [Browser UI](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/frontend/index.html): `frontend/index.html`
- [FastAPI routes](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py): `backend/main.py`

### Recommendations

- [Intent extraction](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/agent.py): `backend/agent.py`
- [Scoring and explanations](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/agent.py): `backend/agent.py`
- [Catalog access](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/product_engine.py): `backend/product_engine.py`
- [Seeded catalog](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/data/products.csv): `data/products.csv`

### Commerce operations

- [Cart operations](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py): `backend/main.py`
- [Checkout and order placement](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py): `backend/main.py`
- [Test payment result](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/payment.py): `backend/payment.py`
- [Order lookup and status](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/backend/main.py): `backend/main.py`

### Local data

- [SQLite order store](https://github.com/kummethachandrikareddy2006-byte/paypilot-ai/blob/main/database/db.py): `database/db.py`

### Other components

- **Shopper**

## Connections

- Shopper → Browser UI: submits request (evidence: `README.md`)
- Browser UI → FastAPI routes: calls API (evidence: `README.md`)
- FastAPI routes → Intent extraction: invokes agent (evidence: `backend/main.py`)
- Intent extraction → Scoring and explanations: scores matches (evidence: `README.md`)
- Scoring and explanations → Seeded catalog: searches catalog (evidence: `README.md`)
- FastAPI routes → Catalog access: looks up products (evidence: `backend/main.py`)
- Catalog access → Seeded catalog: reads CSV (evidence: `backend/product_engine.py`)
- FastAPI routes → Cart operations: manages cart (evidence: `backend/main.py`)
- Shopper → Checkout and order placement: confirms order (evidence: `README.md`)
- FastAPI routes → Checkout and order placement: handles checkout (evidence: `backend/main.py`)
- Checkout and order placement → SQLite order store: saves order (evidence: `backend/main.py`)
- FastAPI routes → Order lookup and status: serves order routes (evidence: `backend/main.py`)
- Order lookup and status → SQLite order store: reads and updates (evidence: `backend/main.py`)
- FastAPI routes → Test payment result: uses payment helper (evidence: `backend/main.py`)