How kabiththananparan/shopmate-lk works
1. Repository shape
- This is a single Next.js application under frontend/; there is no separate backend service.
- The app uses the Next.js App Router, so the main architecture split is between client UI components and server route handlers.
2. Primary user-facing surface
- frontend/app/ai.tsx is the main experience: chat input, voice input, product result cards, cart actions, checkout flow, and the final success/payment card.
- frontend/app/page.tsx likely mounts this experience, while layout.tsx and globals.css provide the app shell and styling.
- CheckoutProgress.tsx is a focused UI component for the guided checkout steps.
3. Client-side interaction model
- Users can interact by text or browser voice input via the Web Speech API.
- The UI keeps a persistent cart in browser localStorage, so cart state survives refreshes without a server session.
- The frontend also drives the checkout wizard locally, collecting delivery and recipient details step-by-step.
4. Server-side orchestration boundary
- frontend/app/api/chat/route.ts is the core backend orchestrator.
- It handles conversational intent, checkout state progression, product search, gift-finder logic, and calls to external AI/commerce services.
- This route is the main boundary where free-form user messages are transformed into structured shopping actions.
5. Language normalization layer
- frontend/services/language/sinhala.ts and tanglish.ts normalize user queries before search or intent matching.
- This is important because the app is designed for Sri Lankan shoppers using English, Tanglish-style Sinhala, or normalized Sinhala phrases.
- In the architecture diagram, this sits between raw user input and product/search logic.
6. Commerce integration layer
- frontend/services/mcp/kapruka.ts is the service wrapper for the Kapruka MCP endpoint.
- It exposes the commerce capabilities used by the app: product search, product details, delivery checks, order creation, order tracking, and category listing.
- The MCP layer is the external commerce boundary; the app itself does not own inventory or fulfillment data.
7. Mapping and translation of external data
- productMapper.ts, searchMapper.ts, searchProducts.ts, and cityMapper.ts convert MCP responses into app-friendly shapes.
- This is a key boundary because Kapruka data must be normalized before it can be rendered as rich product cards or used in checkout.
- types/product.ts and types/chat.ts define the data contracts shared across these layers.
8. AI conversation layer
- The README indicates Groq with llama-3.1-8b-instant powers conversational responses and recommendations.
- The architecture is not “LLM-only”; the model works alongside deterministic intent handling and MCP tool calls.
- In practice, the app blends LLM guidance with structured commerce actions so product search and checkout stay reliable.
9. Checkout and order creation flow
- The checkout sequence is guided and finite: confirm → city → recipient → phone → date → address → gift.
- The final step triggers Kapruka MCP order creation and returns an order id, total, and external payment link.
- This creates a clear boundary between the app’s checkout wizard and Kapruka’s actual fulfillment/payment flow.
10. External rendering and infrastructure constraints
- Product images are rendered through next/image, with allowed external hosts configured in next.config.ts.
- This means image delivery is partially controlled by Next.js image optimization and host allowlisting.
- If new product CDNs are introduced, they must be added to that config to keep images working.
11. Developer/test surfaces
- frontend/app/api/test-product, test-delivery, test-mcp, and test-colombo are diagnostic routes for validating MCP behavior and specific flows.
- frontend/app/api/tools/route.ts suggests a tool-oriented endpoint, likely for inspecting or exposing MCP capabilities separately from the main chat flow.
- These routes support manual verification and demo readiness rather than the end-user journey.
12. Documentation and protocol context
- docs/MCP.txt and docs/MCP.docx provide MCP protocol/reference material for the external commerce integration.
- frontend/services/mcp/README.md likely documents the local MCP client layer.
- For an architecture diagram, the most important external dependencies to show are Groq and Kapruka MCP, with the Next.js app acting as the orchestrator between them and the browser UI.
Main entry points: kapruka.ts Kapruka MCP · route.ts Chat API · ai.tsx AI shop · searchProducts.ts Search flow
Components 23
Client app
Browser UI and local checkout state
- Home page · Mounts the main shopping experience
frontend/app/page.tsx - AI shop · Chat, voice, product cards, cart, checkout, success view
frontend/app/ai.tsx - Checkout steps · Guided finite checkout progress component
frontend/app/CheckoutProgress.tsx - App shell · Shared shell for the app route tree
frontend/app/layout.tsx - Global styles · App-wide styling and visual reset
frontend/app/globals.css
Server routes
Next.js API handlers and orchestration
- Chat API · Transforms user messages into shopping actions
frontend/app/api/chat/route.ts - Tools API · Exposes tool-oriented inspection or helper behavior
frontend/app/api/tools/route.ts - Product test · Validates product lookup and mapping behavior
frontend/app/api/test-product/route.ts - Delivery test · Validates delivery and city lookup behavior
frontend/app/api/test-delivery/route.ts - MCP test · Exercised MCP integration directly
frontend/app/api/test-mcp/route.ts - Colombo test · City-specific validation path
frontend/app/api/test-colombo/route.ts
Services
Language normalization and commerce integration
- Sinhala norm · Normalizes Sinhala queries and variants
frontend/services/language/sinhala.ts - Tanglish norm · Normalizes Tanglish-style Sinhala input
frontend/services/language/tanglish.ts - Kapruka MCP · Wrapper for search, product, delivery, order, and categories
frontend/services/mcp/kapruka.ts - Search flow · Searches and prepares product discovery results
frontend/services/mcp/searchProducts.ts
Contracts
Shared types and mapping boundaries
- Product map · Converts product data to app-friendly shape
frontend/services/mcp/productMapper.ts - Search map · Converts search responses for UI consumption
frontend/services/mcp/searchMapper.ts - City map · Normalizes city and delivery location data
frontend/services/mcp/cityMapper.ts - Chat types · Conversation, checkout, and intent data shapes
frontend/types/chat.ts - Product types · Product and commerce domain data shapes
frontend/types/product.ts
External systems
Third-party AI and commerce services
- Groq LLM · Conversational model used for guidance and recommendations
- Kapruka service · External commerce and fulfillment backend
- Payment link · External payment and order completion destination
Connections 24
- Home page → AI shop: mounts · Home page renders the main AI shopping experience
- App shell → Home page: wraps · App shell provides shared layout around the page
- App shell → Global styles: loads · Global styles are applied across the app
- AI shop → Checkout steps: uses · Checkout UI embeds the guided progress component
- AI shop → Chat API: sends messages · Client submits text and voice-driven conversation input
- AI shop → Tools API: debugs · UI can reach tool-oriented support flows
- Chat API → Sinhala norm: normalizes · Incoming queries are normalized for Sinhala variants
- Chat API → Tanglish norm: normalizes · Incoming queries are normalized for Tanglish input
- Chat API → Search flow: searches · Structured intent can trigger product discovery
- Chat API → Kapruka MCP: orchestrates · Main backend boundary delegates commerce actions
- Chat API → Groq LLM: consults · LLM provides conversational guidance and recommendations
- Chat API → Chat types: uses · Conversation state and intents use shared contracts
- Search flow → Kapruka MCP: queries · Search flow calls the commerce backend
- Search flow → Search map: maps · Search results are normalized for the app
- Kapruka MCP → Product map: maps · Product payloads are converted into app shapes
- Kapruka MCP → City map: maps · City and delivery data are normalized
- Kapruka MCP → Product types: returns · Commerce data is represented with product contracts
- Product test → Kapruka MCP: validates · Diagnostic route exercises product lookup behavior
- Delivery test → Kapruka MCP: validates · Diagnostic route exercises delivery lookup behavior
- MCP test → Kapruka MCP: validates · Diagnostic route exercises MCP connectivity
- Colombo test → City map: validates · City-specific route checks location normalization
- Tools API → Kapruka MCP: exposes · Tool endpoint surfaces commerce capabilities
- Chat API → Payment link: redirects · Order creation resolves to external payment completion
- Kapruka MCP → Kapruka service: calls · Local wrapper delegates to external Kapruka services