# svihijayasinghe15-sudo/kapi-kapruka-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent
- Repository: https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent

## Overview

Kapi Shopping Agent is a web-based Kapruka shopping assistant. A shopper starts in the chat UI, sends a message to the chat API, and receives an AI-generated reply with live product results; the API also has a separate order-tracking path. The UI presents product cards and cart controls. The sampled API route calls Kapruka and Gemini directly; a separate chat-service/conversation-engine path is also present, but the excerpts do not show it being invoked by that route. Several UI and API details are inferred only from the tree or partial excerpts.

Main entry points: [`app/page.tsx`](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/page.tsx) (Shopping page), [`app/api/chat/route.ts`](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts) (Chat endpoint), [`lib/conversation-engine.ts`](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/conversation-engine.ts) (Conversation engine), [`lib/kapruka-mcp.ts`](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/kapruka-mcp.ts) (Kapruka MCP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Shopping interface"]
  node_page["Shopping page<br/>[page.tsx]"]
  node_chatui["Chat interface<br/>[ChatWindow.tsx]"]
  node_welcome["Welcome screen<br/>[WelcomeScreen.tsx]"]
  node_productui["Product display<br/>[ProductCard.tsx]"]
  node_cartui["Cart panels<br/>[CartPanel.tsx]"]
  node_drawer["Cart drawer<br/>[CartDrawer.tsx]"]
end

subgraph group_api["Chat API"]
  node_chatapi["Chat endpoint<br/>[route.ts]"]
  node_track["Order tracking<br/>[route.ts]"]
  node_search["Product search<br/>[route.ts]"]
end

subgraph group_engine["Conversation engine"]
  node_service["Chat service<br/>[chat-service.ts]"]
  node_enginecore["Conversation engine"]
  node_parser["Result parsing<br/>[kapruka-parser.ts]"]
  node_query["Query extraction<br/>[product-search.ts]"]
end

subgraph group_integrations["External services"]
  node_kapruka["Kapruka MCP<br/>[kapruka-mcp.ts]"]
  node_gemini["Gemini AI"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_page
node_page -->|"shows"| node_welcome
node_page -->|"renders"| node_chatui
node_page -->|"posts message"| node_chatapi
node_chatapi -->|"routes tracking"| node_track
node_chatapi -->|"extracts search"| node_search
node_track -->|"tracks order"| node_kapruka
node_search -->|"searches products"| node_kapruka
node_chatapi -->|"generates reply"| node_gemini
node_chatapi -->|"returns response"| node_page
node_page -->|"renders results"| node_productui
node_page -->|"updates cart"| node_cartui
node_page -->|"opens cart"| node_drawer
node_service -->|"processes chat"| node_enginecore
node_enginecore -->|"extracts query"| node_query
node_enginecore -->|"searches products"| node_kapruka
node_enginecore -->|"parses results"| node_parser
node_enginecore -->|"generates response"| node_gemini

click node_page "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/page.tsx"
click node_chatui "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/chat/ChatWindow.tsx"
click node_welcome "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/chat/WelcomeScreen.tsx"
click node_productui "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/products/ProductCard.tsx"
click node_cartui "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/cart/CartPanel.tsx"
click node_drawer "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/cart/CartDrawer.tsx"
click node_chatapi "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts"
click node_track "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts"
click node_search "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts"
click node_service "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/ai/chat-service.ts"
click node_enginecore "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/conversation-engine.ts"
click node_parser "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/kapruka-parser.ts"
click node_query "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/product-search.ts"
click node_kapruka "https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/kapruka-mcp.ts"

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_page,node_chatui,node_welcome,node_productui,node_cartui,node_drawer toneBlue
class node_chatapi,node_track,node_search toneAmber
class node_service,node_enginecore,node_parser,node_query toneMint
class node_kapruka,node_gemini toneRose
class node_shopper toneIndigo
```

## Components

### Shopping interface

- [Shopping page](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/page.tsx): `app/page.tsx`
- [Chat interface](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/chat/ChatWindow.tsx): `components/chat/ChatWindow.tsx`
- [Welcome screen](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/chat/WelcomeScreen.tsx): `components/chat/WelcomeScreen.tsx`
- [Product display](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/products/ProductCard.tsx): `components/products/ProductCard.tsx`
- [Cart panels](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/cart/CartPanel.tsx): `components/cart/CartPanel.tsx`
- [Cart drawer](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/components/cart/CartDrawer.tsx): `components/cart/CartDrawer.tsx`

### Chat API

- [Chat endpoint](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Order tracking](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Product search](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/app/api/chat/route.ts): `app/api/chat/route.ts`

### Conversation engine

- [Chat service](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/ai/chat-service.ts): `lib/ai/chat-service.ts`
- [Conversation engine](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/conversation-engine.ts): `lib/conversation-engine.ts`
- [Result parsing](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/kapruka-parser.ts): `lib/kapruka-parser.ts`
- [Query extraction](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/product-search.ts): `lib/product-search.ts`

### External services

- [Kapruka MCP](https://github.com/svihijayasinghe15-sudo/kapi-kapruka-ai-agent/blob/main/lib/kapruka-mcp.ts): `lib/kapruka-mcp.ts`
- **Gemini AI**

### Other components

- **Shopper**

## Connections

- Shopper → Shopping page: uses
- Shopping page → Welcome screen: shows
- Shopping page → Chat interface: renders
- Shopping page → Chat endpoint: posts message
- Chat endpoint → Order tracking: routes tracking
- Chat endpoint → Product search: extracts search
- Order tracking → Kapruka MCP: tracks order
- Product search → Kapruka MCP: searches products
- Chat endpoint → Gemini AI: generates reply
- Chat endpoint → Shopping page: returns response
- Shopping page → Product display: renders results
- Shopping page → Cart panels: updates cart
- Shopping page → Cart drawer: opens cart
- Chat service → Conversation engine: processes chat
- Conversation engine → Query extraction: extracts query
- Conversation engine → Kapruka MCP: searches products
- Conversation engine → Result parsing: parses results
- Conversation engine → Gemini AI: generates response