How hamdhanhasmy/kapruka-ai-shopping-agent works
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: page.tsx App page · mcp.ts MCP API · api.ts API client · mcpClient.ts MCP client
Components 17
Frontend
Next.js conversational UI and presentation layer
- App page · Main UI orchestrator for the split-pane experience and application state
frontend/src/app/page.tsx - API client · Client-side integration point for backend calls
frontend/src/utils/api.ts - Chat · Primary conversational interface
frontend/src/components/ChatInterface.tsx - Products · Renders catalog items and product summaries
frontend/src/components/ProductCard.tsx - Gift builder · Assembles gift boxes and bundle selections
frontend/src/components/GiftBoxBuilder.tsx - Logistics · Shows perishability and delivery feedback
frontend/src/components/LogisticsPanel.tsx - Tracking · Displays delivery and fulfillment status
frontend/src/components/TrackingCard.tsx - Countdown · Shows price-lock and payment deadline timer
frontend/src/components/CountdownCard.tsx - Styling · Global styling and premium visual system
frontend/src/app/globals.css
Backend
Express/TypeScript orchestration layer
- Server · Backend entrypoint and CORS boundary
backend/src/index.ts - MCP API · API surface consumed by the frontend, including MCP-driven actions and diagnostics
backend/src/routes/mcp.ts - NLP service · Handles intent understanding, multilingual phrasing, Gemini key rotation, and fallback responses
backend/src/services/nlpService.ts - MCP client · Connects to the Kapruka MCP gateway over streamable HTTP/SSE transport
backend/src/services/mcpClient.ts - Bundler · Builds budget-constrained hamper bundles and item selections
backend/src/services/bundlerService.ts - Validator · Validates API inputs and request data at the backend boundary
backend/src/utils/validator.ts
External Services
Upstream AI and commerce integrations
- Gemini API · External model provider used for intent and response generation
- Kapruka MCP · External catalog, commerce, and logistics tool gateway
Connections 21
- 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