# hamdhanhasmy/kapruka-ai-shopping-agent architecture

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

- Interactive diagram: https://gitdiagram.com/hamdhanhasmy/kapruka-ai-shopping-agent
- Repository: https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent

## Overview

1. **System shape:** This repo is a decoupled two-tier application: a **Next.js frontend** in `frontend/` and an **Express/TypeScript backend** in `backend/`. The frontend is the conversational presentation layer; the backend is the orchestration layer that talks to external AI and Kapruka services.

2. **Frontend boundary:** `frontend/src/app/page.tsx` acts as the main coordinator for the split-pane experience and overall UI state. The app is styled as a premium magazine-like interface via `globals.css` and Tailwind. `frontend/src/utils/api.ts` is the only obvious client-side integration point to the backend.

3. **Frontend subviews:** The UI is broken into focused components: `ChatInterface` for conversation, `ProductCard` for catalog items, `GiftBoxBuilder` for hamper assembly, `LogisticsPanel` for delivery/perishability feedback, `TrackingCard` for delivery status, and `CountdownCard` for the 60-minute price-lock/payment timer. These components imply a single-page orchestration flow rather than separate screens.

4. **Backend entry and routing:** `backend/src/index.ts` is the server bootstrap and CORS boundary. `backend/src/routes/mcp.ts` exposes the API surface consumed by the frontend, including MCP-driven actions and a test/diagnostic path noted in the README.

5. **Core orchestration services:** `backend/src/services/nlpService.ts` handles intent understanding and response generation, including the documented **Gemini API key rotation** and fallback behavior. This is the main intelligence layer for multilingual phrasing and vernacular inputs.

6. **External tool gateway:** `backend/src/services/mcpClient.ts` wraps the connection to the **Kapruka MCP gateway** over streamable HTTP/SSE transport. In architecture terms, this is the backend’s adapter to the external commerce/catalog/logistics tool system.

7. **Shopping optimization path:** `backend/src/services/bundlerService.ts` is a separate domain service for constructing budget-constrained bundles. It appears to run parallel item search/selection logic and provides the “smart hamper optimizer” behavior described in the README.

8. **Validation and fallback helpers:** `backend/src/utils/validator.ts` suggests request/input validation at the API boundary. The presence of `scratch_search.ts`, `scratch_search_client.ts`, and `test-mcp-debug.ts` indicates local helper flows for search experimentation and MCP troubleshooting, separate from the main production route.

9. **Primary data flow:** User input enters the frontend chat or product builder, the frontend calls the backend through `api.ts`, the backend uses NLP to interpret intent, then either queries MCP tools or runs bundling/validation logic, and finally returns structured results for the frontend cards/panels to render. The frontend is therefore a thin orchestration client, not a source of business logic.

10. **External dependencies and failure handling:** The architecture depends materially on two external services: the **Kapruka MCP endpoint** and **Gemini APIs**. The README also describes automatic API-key rotation, budget fallback suggestions, shipping verification, and a 60-minute checkout link, which means the backend is designed to degrade gracefully instead of hard-failing when upstream limits or constraints are hit.

11. **Deployment boundary:** The apps are deployed separately: the backend as a standalone Node service with environment-driven configuration, and the frontend as a static/server-rendered Next.js deployment. `NEXT_PUBLIC_API_BASE_URL` connects the frontend to the backend across hosts, so CORS and environment configuration are important architectural boundaries.

Main entry points: [`frontend/src/app/page.tsx`](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/app/page.tsx) (App page), [`backend/src/routes/mcp.ts`](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/routes/mcp.ts) (MCP API), [`frontend/src/utils/api.ts`](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/utils/api.ts) (API client), [`backend/src/services/mcpClient.ts`](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/mcpClient.ts) (MCP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_page["App page<br/>next coordinator<br/>[page.tsx]"]
  node_frontend_api["API client<br/>http client<br/>[api.ts]"]
  node_frontend_chat["Chat<br/>conversation view<br/>[ChatInterface.tsx]"]
  node_frontend_product["Products<br/>catalog card<br/>[ProductCard.tsx]"]
  node_frontend_bundle["Gift builder<br/>hamper composer<br/>[GiftBoxBuilder.tsx]"]
  node_frontend_logistics["Logistics<br/>delivery panel<br/>[LogisticsPanel.tsx]"]
  node_frontend_tracking["Tracking<br/>status card<br/>[TrackingCard.tsx]"]
  node_frontend_countdown["Countdown<br/>timer card<br/>[CountdownCard.tsx]"]
  node_frontend_style["Styling<br/>ui theme<br/>[globals.css]"]
end

subgraph group_backend["Backend"]
  node_backend_boot["Server<br/>express bootstrap<br/>[index.ts]"]
  node_backend_route["MCP API<br/>route layer<br/>[mcp.ts]"]
  node_backend_nlp["NLP service<br/>intent engine<br/>[nlpService.ts]"]
  node_backend_mcp["MCP client<br/>tool adapter<br/>[mcpClient.ts]"]
  node_backend_bundle["Bundler<br/>optimization service<br/>[bundlerService.ts]"]
  node_backend_validator["Validator<br/>request guard<br/>[validator.ts]"]
end

subgraph group_external["External Services"]
  node_external_gemini{{"Gemini API<br/>ai provider"}}
  node_external_kapruka{{"Kapruka MCP<br/>commerce gateway"}}
end

node_frontend_page -->|"coordinates"| node_frontend_chat
node_frontend_page -->|"renders"| node_frontend_product
node_frontend_page -->|"orchestrates"| node_frontend_bundle
node_frontend_page -->|"shows"| node_frontend_logistics
node_frontend_page -->|"shows"| node_frontend_tracking
node_frontend_page -->|"shows"| node_frontend_countdown
node_frontend_page -->|"styles"| node_frontend_style
node_frontend_chat -->|"calls"| node_frontend_api
node_frontend_bundle -->|"calls"| node_frontend_api
node_frontend_logistics -->|"calls"| node_frontend_api
node_frontend_tracking -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_route
node_backend_boot -->|"mounts"| node_backend_route
node_backend_route -->|"validates"| node_backend_validator
node_backend_route -->|"interprets"| node_backend_nlp
node_backend_route -->|"optimizes"| node_backend_bundle
node_backend_route -->|"tools"| node_backend_mcp
node_backend_nlp -->|"uses"| node_external_gemini
node_backend_mcp -->|"connects"| node_external_kapruka
node_backend_bundle -->|"queries"| node_backend_mcp
node_backend_route -->|"responds to"| node_frontend_page

click node_frontend_page "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/app/page.tsx"
click node_frontend_api "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/utils/api.ts"
click node_frontend_chat "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/ChatInterface.tsx"
click node_frontend_product "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/ProductCard.tsx"
click node_frontend_bundle "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/GiftBoxBuilder.tsx"
click node_frontend_logistics "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/LogisticsPanel.tsx"
click node_frontend_tracking "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/TrackingCard.tsx"
click node_frontend_countdown "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/CountdownCard.tsx"
click node_frontend_style "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/app/globals.css"
click node_backend_boot "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/index.ts"
click node_backend_route "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/routes/mcp.ts"
click node_backend_nlp "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/nlpService.ts"
click node_backend_mcp "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/mcpClient.ts"
click node_backend_bundle "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/bundlerService.ts"
click node_backend_validator "https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/utils/validator.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_frontend_page,node_frontend_api,node_frontend_chat,node_frontend_product,node_frontend_bundle,node_frontend_logistics,node_frontend_tracking,node_frontend_countdown,node_frontend_style toneBlue
class node_backend_boot,node_backend_route,node_backend_nlp,node_backend_mcp,node_backend_bundle,node_backend_validator toneAmber
class node_external_gemini,node_external_kapruka toneMint
```

## Components

### Frontend

Next.js conversational UI and presentation layer

- [App page](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/app/page.tsx): next coordinator · Main UI orchestrator for the split-pane experience and application state · `frontend/src/app/page.tsx`
- [API client](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/utils/api.ts): http client · Client-side integration point for backend calls · `frontend/src/utils/api.ts`
- [Chat](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/ChatInterface.tsx): conversation view · Primary conversational interface · `frontend/src/components/ChatInterface.tsx`
- [Products](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/ProductCard.tsx): catalog card · Renders catalog items and product summaries · `frontend/src/components/ProductCard.tsx`
- [Gift builder](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/GiftBoxBuilder.tsx): hamper composer · Assembles gift boxes and bundle selections · `frontend/src/components/GiftBoxBuilder.tsx`
- [Logistics](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/LogisticsPanel.tsx): delivery panel · Shows perishability and delivery feedback · `frontend/src/components/LogisticsPanel.tsx`
- [Tracking](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/TrackingCard.tsx): status card · Displays delivery and fulfillment status · `frontend/src/components/TrackingCard.tsx`
- [Countdown](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/components/CountdownCard.tsx): timer card · Shows price-lock and payment deadline timer · `frontend/src/components/CountdownCard.tsx`
- [Styling](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/frontend/src/app/globals.css): ui theme · Global styling and premium visual system · `frontend/src/app/globals.css`

### Backend

Express/TypeScript orchestration layer

- [Server](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/index.ts): express bootstrap · Backend entrypoint and CORS boundary · `backend/src/index.ts`
- [MCP API](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/routes/mcp.ts): route layer · API surface consumed by the frontend, including MCP-driven actions and diagnostics · `backend/src/routes/mcp.ts`
- [NLP service](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/nlpService.ts): intent engine · Handles intent understanding, multilingual phrasing, Gemini key rotation, and fallback responses · `backend/src/services/nlpService.ts`
- [MCP client](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/mcpClient.ts): tool adapter · Connects to the Kapruka MCP gateway over streamable HTTP/SSE transport · `backend/src/services/mcpClient.ts`
- [Bundler](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/services/bundlerService.ts): optimization service · Builds budget-constrained hamper bundles and item selections · `backend/src/services/bundlerService.ts`
- [Validator](https://github.com/hamdhanhasmy/kapruka-ai-shopping-agent/blob/main/backend/src/utils/validator.ts): request guard · Validates API inputs and request data at the backend boundary · `backend/src/utils/validator.ts`

### External Services

Upstream AI and commerce integrations

- **Gemini API**: ai provider · External model provider used for intent and response generation
- **Kapruka MCP**: commerce gateway · External catalog, commerce, and logistics tool gateway

## Connections

- App page → Chat: coordinates · Page composes the conversational experience
- App page → Products: renders · Page surfaces product cards in the main flow
- App page → Gift builder: orchestrates · Page manages hamper-building interactions
- App page → Logistics: shows · Page includes logistics feedback in the split view
- App page → Tracking: shows · Page includes delivery status cards
- App page → Countdown: shows · Page includes the checkout timer
- App page → Styling: styles · Global styling defines the app's visual presentation
- Chat → API client: calls · Conversation UI sends user input to backend endpoints
- Gift builder → API client: calls · Bundle actions are submitted through the shared API client
- Logistics → API client: calls · Logistics updates are fetched from the backend
- Tracking → API client: calls · Tracking status is loaded through backend APIs
- API client → MCP API: requests · Frontend talks to the MCP route surface across hosts
- Server → MCP API: mounts · Server registers the MCP API routes
- MCP API → Validator: validates · Requests are checked at the API boundary
- MCP API → NLP service: interprets · Route hands conversational input to NLP processing
- MCP API → Bundler: optimizes · Route delegates hamper construction to bundling logic
- MCP API → MCP client: tools · Route delegates commerce and logistics actions to MCP
- NLP service → Gemini API: uses · NLP service depends on Gemini for generation and fallback rotation
- MCP client → Kapruka MCP: connects · MCP client connects to the Kapruka tool gateway
- Bundler → MCP client: queries · Bundler can use tool data for item selection and constraints
- MCP API → App page: responds to · Backend returns structured results for the UI to render
