# rasaljayasinghe/nayana-kapruka architecture

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

- Interactive diagram: https://gitdiagram.com/rasaljayasinghe/nayana-kapruka
- Repository: https://github.com/rasaljayasinghe/nayana-kapruka

## Overview

1. **Product shape**
   - This is a Next.js 16 App Router application for a conversational shopping assistant called **Nayana** for Kapruka Sri Lanka.
   - The app is centered on a full-screen chat experience, but it also includes product browsing, cart review, and checkout handoff.

2. **Top-level runtime boundary**
   - The architecture splits cleanly into **client UI** and **server route handlers**.
   - Client-side components handle the conversational shell, product cards, cart state, voice interaction, and page transitions.
   - Server-side API routes handle LLM chat, product lookup, speech synthesis, tracking, and checkout/order creation.

3. **Primary user flow**
   - Users start in chat, ask for products or help, and Nayana searches the Kapruka catalog through MCP tools.
   - Selected items are added to a **session cart stored in localStorage**, not a database.
   - Users then move to a dedicated **order review** screen, confirm the purchase, and only then does the app create the actual Kapruka order.

4. **Chat orchestration layer**
   - The chat subsystem is the core orchestration layer: `src/components/chat` and `src/lib/chat-*`, `nayana-*`, `mcp-actions`, and `kapruka-mcp`.
   - It coordinates assistant messaging, tool results, suggestions, delegation indicators, and conversation state.
   - The UI exposes “agent” roles for clarity, but these map to real tool execution rather than separate backend services.

5. **LLM and tool integration**
   - `/api/chat` is the main AI entry point and uses AI SDK v6 with MiniMax as the model provider.
   - Tooling is mediated through **Kapruka MCP** at `https://mcp.kapruka.com/mcp`, which provides product search, delivery checks, and tracking.
   - The assistant is intentionally prevented from directly placing orders; `kapruka_create_order` is reserved for the explicit checkout step.

6. **Checkout boundary**
   - Checkout is isolated in `/api/checkout`.
   - The review page gathers cart contents and delivery details, then a confirmation modal gates the final request.
   - That route calls Kapruka’s order creation tool and returns a live payment link, keeping purchase authorization outside the chat agent.

7. **Voice and speech subsystem**
   - Voice is a separate capability with three modes: hands-free conversation, per-message playback, and one-shot dictation.
   - `useVoiceConversation`, `useSpeechInput`, `useNayanaSpeech`, and the ElevenLabs-backed `/api/speech` route support this loop.
   - The voice flow is designed so speech input and speech output remain additive to chat, not a replacement for it.

8. **Product discovery and merchandising UI**
   - Product browsing is implemented as a dedicated UI layer under `src/components/product` and `src/app/product/[id]`.
   - This includes cards, compare rows, carousel, detail modal/shell, and discovery grid components.
   - These components connect product exploration to the cart, and product detail pages can participate in the same shopping session as chat.

9. **Order review and cart state**
   - The cart is managed locally through provider state plus persistent browser storage.
   - `CartProvider`, `MobileBasketProvider`, and order-review components share a single session-based shopping context.
   - This is the boundary where UI validation and budget caps are enforced before any server-side order creation happens.

10. **App shell and shared UI composition**
   - `AppProviders` wires the global providers for cart, toasts, voice session state, and mobile basket behavior.
   - The main layout uses shared chat shell components, brand/header components, and reusable UI primitives in `src/components/ui`.
   - This keeps the app visually consistent while allowing the chat, product, and order surfaces to reuse the same design system.

11. **Language and regional behavior**
   - The app supports **English, Sinhala, and Tamil**, with code-switch-aware Tanglish mirroring.
   - Language selection is passed with chat requests and is part of the prompt/system behavior, not a separate translation service.
   - Sri Lankan context helpers and parsing utilities shape catalog and language outputs to feel local to Kapruka’s audience.

12. **External dependencies and deployment constraints**
   - The meaningful external systems are Kapruka MCP, MiniMax for chat generation, and ElevenLabs for voice.
   - Netlify is the deployment target, so the chat route is tuned for function time limits and multi-step tool loops.
   - There is no backend database; persistence is deliberately lightweight and browser/session-oriented.

13. **Repo structure to diagram**
   - A clear diagram would show: browser UI and providers → chat/product/order pages → API routes → external services.
   - The important arrows are chat to MCP, checkout to Kapruka order creation, voice to ElevenLabs, and cart/order review staying client-side until confirmation.

Main entry points: [`src/components/chat/ChatShell.tsx`](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/ChatShell.tsx) (Chat shell), [`src/app/api/chat/route.ts`](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/components/providers/AppProviders.tsx`](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/AppProviders.tsx) (AppProviders), [`src/hooks/useVoiceConversation.ts`](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/hooks/useVoiceConversation.ts) (Voice hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_app_layout["App shell<br/>layout<br/>[layout.tsx]"]
  node_app_providers["AppProviders<br/>provider wiring<br/>[AppProviders.tsx]"]
  node_cart_provider["Cart state<br/>session cart<br/>[CartProvider.tsx]"]
  node_voice_session["Voice session<br/>voice state"]
  node_home_page["Chat home<br/>entry page<br/>[page.tsx]"]
  node_chat_shell["Chat shell<br/>conversation UI<br/>[ChatShell.tsx]"]
  node_message_list["Messages<br/>chat view<br/>[MessageList.tsx]"]
  node_composer["Composer<br/>input UI<br/>[Composer.tsx]"]
  node_voice_hooks["Voice hooks<br/>voice runtime"]
  node_product_grid["Browse grid<br/>merchandising UI"]
  node_product_detail_page["Product page<br/>detail page<br/>[page.tsx]"]
  node_product_detail_client["Detail client<br/>product view"]
  node_order_review_page["Review page<br/>checkout page<br/>[page.tsx]"]
  node_order_review_content["Review content<br/>checkout UI"]
end

subgraph group_server["Server Routes"]
  node_api_chat["Chat API<br/>ai route<br/>[route.ts]"]
  node_api_checkout["Checkout API<br/>order route<br/>[route.ts]"]
  node_api_speech["Speech API<br/>tts route<br/>[route.ts]"]
  node_api_product["Product API<br/>catalog route<br/>[route.ts]"]
  node_api_track["Track API<br/>tracking route<br/>[route.ts]"]
  node_mcp_actions["MCP actions<br/>tool adapter<br/>[mcp-actions.ts]"]
  node_kapruka_mcp["Kapruka MCP<br/>tool client<br/>[kapruka-mcp.ts]"]
end

subgraph group_external["External Services"]
  node_elevenlabs["ElevenLabs<br/>speech provider"]
  node_minimax["MiniMax<br/>model provider"]
  node_kapruka_backend["Kapruka tools<br/>commerce backend"]
end

node_app_layout -->|"wraps"| node_app_providers
node_app_providers -->|"cart state"| node_cart_provider
node_app_providers -->|"voice state"| node_voice_session
node_home_page -->|"mounts"| node_chat_shell
node_chat_shell -->|"shows"| node_message_list
node_chat_shell -->|"inputs"| node_composer
node_chat_shell -->|"voice"| node_voice_hooks
node_chat_shell -->|"sends"| node_api_chat
node_api_chat -->|"generates"| node_minimax
node_api_chat -->|"tools"| node_mcp_actions
node_mcp_actions -->|"executes"| node_kapruka_mcp
node_kapruka_mcp -->|"calls"| node_kapruka_backend
node_product_grid -->|"navigates"| node_product_detail_page
node_product_detail_page -->|"hydrates"| node_product_detail_client
node_product_detail_client -->|"loads"| node_api_product
node_order_review_page -->|"renders"| node_order_review_content
node_order_review_content -->|"reads cart"| node_cart_provider
node_order_review_content -->|"confirms"| node_api_checkout
node_api_checkout -->|"creates order"| node_kapruka_backend
node_api_speech -->|"synthesizes"| node_elevenlabs
node_api_track -->|"tracks"| node_kapruka_backend
node_voice_hooks -->|"plays"| node_api_speech
node_voice_hooks -->|"dictates"| node_api_chat

click node_app_layout "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/layout.tsx"
click node_app_providers "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/AppProviders.tsx"
click node_cart_provider "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/CartProvider.tsx"
click node_voice_session "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/VoiceSessionContext.tsx"
click node_home_page "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/page.tsx"
click node_chat_shell "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/ChatShell.tsx"
click node_message_list "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/MessageList.tsx"
click node_composer "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/Composer.tsx"
click node_voice_hooks "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/hooks/useVoiceConversation.ts"
click node_product_grid "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/product/ProductDiscoverGrid.tsx"
click node_product_detail_page "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/product/[id]/page.tsx"
click node_product_detail_client "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/product/[id]/ProductDetailPageClient.tsx"
click node_order_review_page "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/order/review/page.tsx"
click node_order_review_content "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/order/OrderReviewContent.tsx"
click node_api_chat "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/chat/route.ts"
click node_api_checkout "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/checkout/route.ts"
click node_api_speech "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/speech/route.ts"
click node_api_product "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/product/[id]/route.ts"
click node_api_track "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/track/route.ts"
click node_mcp_actions "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/lib/mcp-actions.ts"
click node_kapruka_mcp "https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/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_app_layout,node_app_providers,node_cart_provider,node_voice_session,node_home_page,node_chat_shell,node_message_list,node_composer,node_voice_hooks,node_product_grid,node_product_detail_page,node_product_detail_client,node_order_review_page,node_order_review_content toneBlue
class node_api_chat,node_api_checkout,node_api_speech,node_api_product,node_api_track,node_mcp_actions,node_kapruka_mcp toneAmber
class node_elevenlabs,node_minimax,node_kapruka_backend toneMint
```

## Components

### Client UI

Browser-side chat, product browsing, cart, voice, and review surfaces.

- [App shell](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/layout.tsx): layout · Root app layout and global frame. · `src/app/layout.tsx`
- [AppProviders](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/AppProviders.tsx): provider wiring · Global provider composition for cart, toast, voice, and mobile basket state. · `src/components/providers/AppProviders.tsx`
- [Cart state](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/CartProvider.tsx): session cart · Client-side shopping cart stored in provider state and browser storage. · `src/components/providers/CartProvider.tsx`
- [Voice session](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/providers/VoiceSessionContext.tsx): voice state · Shared voice and playback session context. · `src/components/providers/VoiceSessionContext.tsx`
- [Chat home](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/page.tsx): entry page · Main conversational landing page for Nayana. · `src/app/page.tsx`
- [Chat shell](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/ChatShell.tsx): conversation UI · Full-screen chat experience and assistant orchestration surface. · `src/components/chat/ChatShell.tsx`
- [Messages](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/MessageList.tsx): chat view · Renders assistant and user conversation turns. · `src/components/chat/MessageList.tsx`
- [Composer](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/chat/Composer.tsx): input UI · Text entry and chat submission controls. · `src/components/chat/Composer.tsx`
- [Voice hooks](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/hooks/useVoiceConversation.ts): voice runtime · Browser voice conversation and dictation hooks. · `src/hooks/useVoiceConversation.ts`
- [Browse grid](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/product/ProductDiscoverGrid.tsx): merchandising UI · Product discovery grid and cards for browsing catalog items. · `src/components/product/ProductDiscoverGrid.tsx`
- [Product page](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/product/[id]/page.tsx): detail page · Dedicated product route that joins the shopping session. · `src/app/product/[id]/page.tsx`
- [Detail client](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/product/[id]/ProductDetailPageClient.tsx): product view · Interactive product detail shell and cart-aware actions. · `src/app/product/[id]/ProductDetailPageClient.tsx`
- [Review page](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/order/review/page.tsx): checkout page · Session cart and delivery review before purchase confirmation. · `src/app/order/review/page.tsx`
- [Review content](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/components/order/OrderReviewContent.tsx): checkout UI · Cart validation, delivery details, and confirmation gate. · `src/components/order/OrderReviewContent.tsx`

### Server Routes

Next.js API handlers for chat, checkout, speech, product lookup, and tracking.

- [Chat API](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/chat/route.ts): ai route · Main LLM entry point for assistant turns and tool loops. · `src/app/api/chat/route.ts`
- [Checkout API](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/checkout/route.ts): order route · Final order creation and payment-link handoff. · `src/app/api/checkout/route.ts`
- [Speech API](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/speech/route.ts): tts route · Server-side speech synthesis endpoint. · `src/app/api/speech/route.ts`
- [Product API](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/product/[id]/route.ts): catalog route · Product lookup endpoint used by product detail flows. · `src/app/api/product/[id]/route.ts`
- [Track API](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/app/api/track/route.ts): tracking route · Tracking and event capture endpoint. · `src/app/api/track/route.ts`
- [MCP actions](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/lib/mcp-actions.ts): tool adapter · Chat-side tool mediation and action wiring. · `src/lib/mcp-actions.ts`
- [Kapruka MCP](https://github.com/rasaljayasinghe/nayana-kapruka/blob/main/src/lib/kapruka-mcp.ts): tool client · Integration client for catalog, delivery, tracking, and order tools. · `src/lib/kapruka-mcp.ts`

### External Services

Third-party services used for model access, tool execution, speech, and order creation.

- **ElevenLabs**: speech provider · External speech generation service.
- **MiniMax**: model provider · LLM provider used by the chat route.
- **Kapruka tools**: commerce backend · Kapruka MCP-backed product search, checks, tracking, and order creation.

## Connections

- App shell → AppProviders: wraps · Root layout installs global providers.
- AppProviders → Cart state: cart state · Cart context is made available app-wide.
- AppProviders → Voice session: voice state · Voice session context is made available app-wide.
- Chat home → Chat shell: mounts · Home page renders the chat experience.
- Chat shell → Messages: shows · Conversation transcript is rendered in the shell.
- Chat shell → Composer: inputs · User text entry flows through the composer.
- Chat shell → Voice hooks: voice · Hands-free and dictation behavior is layered into chat.
- Chat shell → Chat API: sends · Messages are posted to the chat route.
- Chat API → MiniMax: generates · The chat route calls the model provider.
- Chat API → MCP actions: tools · Assistant tool calls are mediated through the action layer.
- MCP actions → Kapruka MCP: executes · Actions delegate to the Kapruka MCP client.
- Kapruka MCP → Kapruka tools: calls · MCP client reaches Kapruka product and order tools.
- Browse grid → Product page: navigates · Discovery browsing opens product detail routes.
- Product page → Detail client: hydrates · Route renders the interactive product detail client.
- Detail client → Product API: loads · Product details are fetched from the product API.
- Review page → Review content: renders · Review route uses shared checkout UI.
- Review content → Cart state: reads cart · Checkout review is driven by session cart state.
- Review content → Checkout API: confirms · Final confirmation submits the order request.
- Checkout API → Kapruka tools: creates order · Checkout route invokes the order creation tool.
- Speech API → ElevenLabs: synthesizes · Speech endpoint delegates to ElevenLabs.
- Track API → Kapruka tools: tracks · Tracking events are forwarded through the Kapruka integration.
- Voice hooks → Speech API: plays · Voice UI can trigger server-side speech output.
- Voice hooks → Chat API: dictates · Speech input can feed chat requests.