# kabiththananparan/shopmate-lk architecture

> Architecture diagram of the GitHub repository kabiththananparan/shopmate-lk, 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/kabiththananparan/shopmate-lk
- Repository: https://github.com/kabiththananparan/shopmate-lk

## Overview

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: [`frontend/services/mcp/kapruka.ts`](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/kapruka.ts) (Kapruka MCP), [`frontend/app/api/chat/route.ts`](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/chat/route.ts) (Chat API), [`frontend/app/ai.tsx`](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/ai.tsx) (AI shop), [`frontend/services/mcp/searchProducts.ts`](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/searchProducts.ts) (Search flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_page["Home page<br/>app entry<br/>[page.tsx]"]
  node_ai["AI shop<br/>client experience<br/>[ai.tsx]"]
  node_progress["Checkout steps<br/>ui wizard"]
  node_layout["App shell<br/>next layout<br/>[layout.tsx]"]
  node_styles["Global styles<br/>css base<br/>[globals.css]"]
end

subgraph group_server["Server routes"]
  node_chat["Chat API<br/>orchestrator route<br/>[route.ts]"]
  node_tools["Tools API<br/>diagnostic route<br/>[route.ts]"]
  node_testprod["Product test<br/>diagnostic route<br/>[route.ts]"]
  node_testdeliv["Delivery test<br/>diagnostic route<br/>[route.ts]"]
  node_testmcp["MCP test<br/>diagnostic route<br/>[route.ts]"]
  node_testcol["Colombo test<br/>diagnostic route<br/>[route.ts]"]
end

subgraph group_services["Services"]
  node_sinhala["Sinhala norm<br/>language normalize<br/>[sinhala.ts]"]
  node_tanglish["Tanglish norm<br/>language normalize<br/>[tanglish.ts]"]
  node_kapruka["Kapruka MCP<br/>commerce client<br/>[kapruka.ts]"]
  node_search["Search flow<br/>commerce search<br/>[searchProducts.ts]"]
end

subgraph group_contracts["Contracts"]
  node_pmap["Product map<br/>response mapper<br/>[productMapper.ts]"]
  node_smap["Search map<br/>response mapper<br/>[searchMapper.ts]"]
  node_citymap["City map<br/>lookup mapper<br/>[cityMapper.ts]"]
  node_chattypes["Chat types<br/>shared contract<br/>[chat.ts]"]
  node_producttypes["Product types<br/>shared contract<br/>[product.ts]"]
end

subgraph group_external["External systems"]
  node_groq(("Groq LLM<br/>external ai"))
  node_kaprukaserver[("Kapruka service<br/>external commerce")]
  node_payment(("Payment link<br/>external checkout"))
end

node_page -->|"mounts"| node_ai
node_layout -->|"wraps"| node_page
node_layout -->|"loads"| node_styles
node_ai -->|"uses"| node_progress
node_ai -->|"sends messages"| node_chat
node_ai -.->|"debugs"| node_tools
node_chat -->|"normalizes"| node_sinhala
node_chat -->|"normalizes"| node_tanglish
node_chat -->|"searches"| node_search
node_chat -->|"orchestrates"| node_kapruka
node_chat -->|"consults"| node_groq
node_chat -->|"uses"| node_chattypes
node_search -->|"queries"| node_kapruka
node_search -->|"maps"| node_smap
node_kapruka -->|"maps"| node_pmap
node_kapruka -->|"maps"| node_citymap
node_kapruka -->|"returns"| node_producttypes
node_testprod -.->|"validates"| node_kapruka
node_testdeliv -.->|"validates"| node_kapruka
node_testmcp -.->|"validates"| node_kapruka
node_testcol -.->|"validates"| node_citymap
node_tools -.->|"exposes"| node_kapruka
node_chat -->|"redirects"| node_payment
node_kapruka -->|"calls"| node_kaprukaserver

click node_page "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/page.tsx"
click node_ai "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/ai.tsx"
click node_progress "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/CheckoutProgress.tsx"
click node_layout "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/layout.tsx"
click node_styles "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/globals.css"
click node_chat "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/chat/route.ts"
click node_tools "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/tools/route.ts"
click node_testprod "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-product/route.ts"
click node_testdeliv "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-delivery/route.ts"
click node_testmcp "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-mcp/route.ts"
click node_testcol "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-colombo/route.ts"
click node_sinhala "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/language/sinhala.ts"
click node_tanglish "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/language/tanglish.ts"
click node_kapruka "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/kapruka.ts"
click node_search "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/searchProducts.ts"
click node_pmap "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/productMapper.ts"
click node_smap "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/searchMapper.ts"
click node_citymap "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/cityMapper.ts"
click node_chattypes "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/types/chat.ts"
click node_producttypes "https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/types/product.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_ai,node_progress,node_layout,node_styles toneBlue
class node_chat,node_tools,node_testprod,node_testdeliv,node_testmcp,node_testcol toneAmber
class node_sinhala,node_tanglish,node_kapruka,node_search toneMint
class node_pmap,node_smap,node_citymap,node_chattypes,node_producttypes toneRose
class node_groq,node_kaprukaserver,node_payment toneIndigo
```

## Components

### Client app

Browser UI and local checkout state

- [Home page](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/page.tsx): app entry · Mounts the main shopping experience · `frontend/app/page.tsx`
- [AI shop](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/ai.tsx): client experience · Chat, voice, product cards, cart, checkout, success view · `frontend/app/ai.tsx`
- [Checkout steps](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/CheckoutProgress.tsx): ui wizard · Guided finite checkout progress component · `frontend/app/CheckoutProgress.tsx`
- [App shell](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/layout.tsx): next layout · Shared shell for the app route tree · `frontend/app/layout.tsx`
- [Global styles](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/globals.css): css base · App-wide styling and visual reset · `frontend/app/globals.css`

### Server routes

Next.js API handlers and orchestration

- [Chat API](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/chat/route.ts): orchestrator route · Transforms user messages into shopping actions · `frontend/app/api/chat/route.ts`
- [Tools API](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/tools/route.ts): diagnostic route · Exposes tool-oriented inspection or helper behavior · `frontend/app/api/tools/route.ts`
- [Product test](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-product/route.ts): diagnostic route · Validates product lookup and mapping behavior · `frontend/app/api/test-product/route.ts`
- [Delivery test](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-delivery/route.ts): diagnostic route · Validates delivery and city lookup behavior · `frontend/app/api/test-delivery/route.ts`
- [MCP test](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-mcp/route.ts): diagnostic route · Exercised MCP integration directly · `frontend/app/api/test-mcp/route.ts`
- [Colombo test](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/app/api/test-colombo/route.ts): diagnostic route · City-specific validation path · `frontend/app/api/test-colombo/route.ts`

### Services

Language normalization and commerce integration

- [Sinhala norm](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/language/sinhala.ts): language normalize · Normalizes Sinhala queries and variants · `frontend/services/language/sinhala.ts`
- [Tanglish norm](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/language/tanglish.ts): language normalize · Normalizes Tanglish-style Sinhala input · `frontend/services/language/tanglish.ts`
- [Kapruka MCP](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/kapruka.ts): commerce client · Wrapper for search, product, delivery, order, and categories · `frontend/services/mcp/kapruka.ts`
- [Search flow](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/searchProducts.ts): commerce search · Searches and prepares product discovery results · `frontend/services/mcp/searchProducts.ts`

### Contracts

Shared types and mapping boundaries

- [Product map](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/productMapper.ts): response mapper · Converts product data to app-friendly shape · `frontend/services/mcp/productMapper.ts`
- [Search map](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/searchMapper.ts): response mapper · Converts search responses for UI consumption · `frontend/services/mcp/searchMapper.ts`
- [City map](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/services/mcp/cityMapper.ts): lookup mapper · Normalizes city and delivery location data · `frontend/services/mcp/cityMapper.ts`
- [Chat types](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/types/chat.ts): shared contract · Conversation, checkout, and intent data shapes · `frontend/types/chat.ts`
- [Product types](https://github.com/kabiththananparan/shopmate-lk/blob/main/frontend/types/product.ts): shared contract · Product and commerce domain data shapes · `frontend/types/product.ts`

### External systems

Third-party AI and commerce services

- **Groq LLM**: external ai · Conversational model used for guidance and recommendations
- **Kapruka service**: external commerce · External commerce and fulfillment backend
- **Payment link**: external checkout · External payment and order completion destination

## Connections

- 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
