# tehan-hewage/kavi architecture

> Architecture diagram of the GitHub repository tehan-hewage/kavi, 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/tehan-hewage/kavi
- Repository: https://github.com/tehan-hewage/kavi

## Overview

1. **Overall shape**
   - This is a **Next.js 14 App Router** application in TypeScript.
   - The UI is a **single-page, full-screen shopping assistant** centered on chat, with side features for products, cart, checkout, and voice.

2. **Primary user experience layer**
   - The `app/page.tsx` entry point likely assembles the main experience using components under `components/chat`, `components/products`, `components/cart`, `components/checkout`, and `components/voice`.
   - The interaction model is conversational first, but the app also supports direct product browsing and cart/checkout actions.

3. **Server-side API boundary**
   - The main backend surface is the `app/api/*` route set:
     - `api/chat` for the AI shopping agent
     - `api/product` for product lookup/catalog access
     - `api/speak` for text-to-speech
     - `api/transcribe` for speech-to-text
     - `api/voice/token` for voice service auth/token exchange
   - These routes form the boundary between the browser UI and external services.

4. **AI orchestration subsystem**
   - The core agent logic lives in `lib/agent-system-prompt.ts`, `lib/kavi-system-prompt.ts`, `lib/language-detect.ts`, `lib/mcp-tools.ts`, `lib/mcp-client.ts`, and `lib/kapruka-mcp.ts`.
   - The app is designed to route through **Gemini or Anthropic** depending on available environment keys, with the model choice abstracted away from the UI.
   - The chat backend is therefore an orchestration layer: language handling, system prompting, tool use, and fallback/error translation.

5. **External commerce integration**
   - A key boundary is the integration with the **Kapruka MCP server** via Model Context Protocol.
   - The repo suggests tool-based access to live product browsing, availability checks, and catalog queries rather than a static local catalog.
   - This is the main commerce data source feeding product cards, search results, and cartable items.

6. **Cart and checkout flow**
   - Cart state is handled client-side via `components/providers/CartProvider.tsx`, with presentation components in `components/cart`.
   - Checkout UI lives in `components/checkout` and includes delivery date, gift message, and a payment link card.
   - The README indicates pricing logic includes a **flat Sri Lankan delivery fee** and a countdown-based payment prompt, so pricing and urgency are part of the UI state model.

7. **Voice experience**
   - Voice interaction is a separate subsystem spanning `hooks/useAudioCapture.ts`, `hooks/useVoice.ts`, `hooks/useTTS.ts`, `hooks/useGeminiLive.ts`, and UI in `components/voice`.
   - The presence of `api/transcribe`, `api/speak`, and `api/voice/token` shows a full voice pipeline: capture → transcription → agent response → speech output.
   - `components/ui/VoiceOrb.tsx` and `components/voice/VoiceWaveform.tsx` indicate the voice mode has a distinct visual state.

8. **Shared client state and personalization**
   - Several providers coordinate app-wide behavior:
     - `LanguageProvider` for multilingual UI state
     - `CurrencyProvider` for price display
     - `ThemeProvider` for dark/light mode
     - `CartProvider` for shopping state
   - These are important architectural boundaries because they let the chat, product, cart, and checkout surfaces stay synchronized without tight coupling.

9. **Component decomposition**
   - The UI is organized by domain rather than by page:
     - chat: input, message list, bubbles, typing indicator, shell, header
     - products: card, grid, carousel, detail modal
     - cart: drawer, item, summary
     - checkout: form, delivery picker, gift message, pay card
     - shared UI: pills, chips, skeletons, status timeline, buttons
   - This suggests a modular composition model where the chat experience can trigger secondary UI panels instead of navigating to separate pages.

10. **Domain types and shared utilities**
   - `types/cart.ts`, `types/order.ts`, and `types/product.ts` define the commerce data model.
   - `lib/types.ts`, `lib/image-utils.ts`, `lib/animations.ts`, `lib/cultural-calendar.ts`, `lib/sinhala-phrases.ts`, and `styles/*` provide shared logic for presentation, localization, and brand consistency.
   - This keeps business data, cultural language assets, and visual tokens centralized.

11. **Testing and quality gates**
   - The repo has a strong test matrix:
     - unit tests for prompts, language detection, pricing, and Sinhala phrases
     - integration tests for chat API, cart provider, MCP tools, and load behavior
     - component tests for the major UI pieces
     - end-to-end tests covering welcome, search, cart, delivery quote, gift message, checkout, tracking, language switching, dark mode, mobile, and errors
   - This indicates the architecture is built around real user flows, not just isolated components.

12. **Deployment and runtime shape**
   - `vercel.json` suggests deployment on **Vercel**, which fits the App Router + serverless route model.
   - `next.config.mjs`, `tailwind.config.ts`, and `vitest/playwright` config files show a standard modern Next.js stack with separate build, test, and runtime concerns.
   - Environment configuration is central because the app’s AI backend and voice features depend on external API keys and live service access.

13. **How to draw the architecture**
   - The cleanest diagram would place the **browser UI** at the center, fed by:
     - the **Next.js server/API routes** on one side
     - **Kapruka MCP** and **LLM providers** on the other
     - **voice services** as a parallel input/output path
   - Inside the UI, show a shared state layer for language/cart/currency/theme, then domain modules for chat, products, cart, checkout, and voice.

Main entry points: [`app/page.tsx`](https://github.com/tehan-hewage/kavi/blob/main/app/page.tsx) (Home), [`components/chat/ChatShell.tsx`](https://github.com/tehan-hewage/kavi/blob/main/components/chat/ChatShell.tsx) (Chat Shell), [`hooks/useVoice.ts`](https://github.com/tehan-hewage/kavi/blob/main/hooks/useVoice.ts) (Use Voice), [`app/api/chat/route.ts`](https://github.com/tehan-hewage/kavi/blob/main/app/api/chat/route.ts) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_app_page["Home<br/>Next.js entry<br/>[page.tsx]"]
  node_chat_shell["Chat Shell<br/>chat layout<br/>[ChatShell.tsx]"]
  node_chat_input["Chat Input<br/>[ChatInput.tsx]"]
  node_message_list["Messages<br/>chat history<br/>[MessageList.tsx]"]
end

subgraph group_state["Shared State"]
  node_cart_provider["Cart Provider<br/>cart state<br/>[CartProvider.tsx]"]
  node_language_provider["Language Provider<br/>i18n state"]
  node_currency_provider["Currency Provider<br/>money state"]
  node_theme_provider["Theme Provider<br/>theme state<br/>[ThemeProvider.tsx]"]
end

subgraph group_api["Next.js API"]
  node_api_chat["Chat API<br/>agent route<br/>[route.ts]"]
  node_api_product["Product API<br/>catalog route<br/>[route.ts]"]
  node_api_speak["Speak API<br/>tts route<br/>[route.ts]"]
  node_api_transcribe["Transcribe API<br/>stt route<br/>[route.ts]"]
  node_api_voice_token["Voice Token<br/>auth route<br/>[route.ts]"]
end

subgraph group_orchestration["AI Orchestration"]
  node_agent_prompt["Agent Prompt<br/>system prompt"]
  node_language_detect["Language Detect<br/>language logic<br/>[language-detect.ts]"]
  node_mcp_tools["MCP Tools<br/>tooling layer<br/>[mcp-tools.ts]"]
  node_mcp_client["MCP Client<br/>[mcp-client.ts]"]
  node_kapruka_mcp["Kapruka MCP<br/>commerce backend<br/>[kapruka-mcp.ts]"]
end

subgraph group_commerce["Commerce UI"]
  node_product_grid["Product Grid<br/>catalog view<br/>[ProductGrid.tsx]"]
  node_product_card["Product Card<br/>product tile<br/>[ProductCard.tsx]"]
  node_product_modal["Detail Modal<br/>product detail"]
  node_cart_drawer["Cart Drawer<br/>cart panel<br/>[CartDrawer.tsx]"]
  node_cart_summary["Cart Summary<br/>pricing summary<br/>[CartSummary.tsx]"]
  node_checkout_form["Checkout Form<br/>checkout flow<br/>[CheckoutForm.tsx]"]
  node_pay_link["Pay Link<br/>payment prompt<br/>[PayLinkCard.tsx]"]
end

subgraph group_voice["Voice Pipeline"]
  node_voice_button["Voice Button<br/>voice control<br/>[VoiceButton.tsx]"]
  node_voice_waveform["Waveform<br/>voice visualizer<br/>[VoiceWaveform.tsx]"]
  node_use_voice["Use Voice<br/>voice hook<br/>[useVoice.ts]"]
end

node_app_page -->|"assembles"| node_chat_shell
node_app_page -->|"shows"| node_product_grid
node_app_page -->|"includes"| node_cart_drawer
node_app_page -->|"includes"| node_checkout_form
node_app_page -->|"enables"| node_voice_button
node_chat_shell -->|"contains"| node_chat_input
node_chat_shell -->|"contains"| node_message_list
node_cart_provider -->|"drives"| node_cart_drawer
node_cart_provider -->|"drives"| node_cart_summary
node_currency_provider -->|"formats"| node_product_card
node_language_provider -->|"localizes"| node_chat_shell
node_theme_provider -->|"themes"| node_app_page
node_api_chat -->|"uses"| node_agent_prompt
node_api_chat -->|"detects"| node_language_detect
node_api_chat -->|"invokes"| node_mcp_tools
node_mcp_tools -->|"wraps"| node_mcp_client
node_mcp_client -->|"connects"| node_kapruka_mcp
node_api_product -->|"queries"| node_mcp_tools
node_api_speak -->|"supports"| node_voice_button
node_api_transcribe -->|"supports"| node_use_voice
node_api_voice_token -->|"authorizes"| node_use_voice
node_use_voice -->|"renders"| node_voice_waveform
node_use_voice -->|"controls"| node_voice_button
node_product_grid -->|"contains"| node_product_card
node_product_card -->|"opens"| node_product_modal
node_cart_drawer -->|"feeds"| node_checkout_form
node_checkout_form -->|"ends with"| node_pay_link

click node_app_page "https://github.com/tehan-hewage/kavi/blob/main/app/page.tsx"
click node_chat_shell "https://github.com/tehan-hewage/kavi/blob/main/components/chat/ChatShell.tsx"
click node_chat_input "https://github.com/tehan-hewage/kavi/blob/main/components/chat/ChatInput.tsx"
click node_message_list "https://github.com/tehan-hewage/kavi/blob/main/components/chat/MessageList.tsx"
click node_product_grid "https://github.com/tehan-hewage/kavi/blob/main/components/products/ProductGrid.tsx"
click node_product_card "https://github.com/tehan-hewage/kavi/blob/main/components/products/ProductCard.tsx"
click node_product_modal "https://github.com/tehan-hewage/kavi/blob/main/components/products/ProductDetailModal.tsx"
click node_cart_drawer "https://github.com/tehan-hewage/kavi/blob/main/components/cart/CartDrawer.tsx"
click node_cart_summary "https://github.com/tehan-hewage/kavi/blob/main/components/cart/CartSummary.tsx"
click node_checkout_form "https://github.com/tehan-hewage/kavi/blob/main/components/checkout/CheckoutForm.tsx"
click node_pay_link "https://github.com/tehan-hewage/kavi/blob/main/components/checkout/PayLinkCard.tsx"
click node_cart_provider "https://github.com/tehan-hewage/kavi/blob/main/components/providers/CartProvider.tsx"
click node_language_provider "https://github.com/tehan-hewage/kavi/blob/main/components/providers/LanguageProvider.tsx"
click node_currency_provider "https://github.com/tehan-hewage/kavi/blob/main/components/providers/CurrencyProvider.tsx"
click node_theme_provider "https://github.com/tehan-hewage/kavi/blob/main/components/providers/ThemeProvider.tsx"
click node_api_chat "https://github.com/tehan-hewage/kavi/blob/main/app/api/chat/route.ts"
click node_api_product "https://github.com/tehan-hewage/kavi/blob/main/app/api/product/route.ts"
click node_api_speak "https://github.com/tehan-hewage/kavi/blob/main/app/api/speak/route.ts"
click node_api_transcribe "https://github.com/tehan-hewage/kavi/blob/main/app/api/transcribe/route.ts"
click node_api_voice_token "https://github.com/tehan-hewage/kavi/blob/main/app/api/voice/token/route.ts"
click node_agent_prompt "https://github.com/tehan-hewage/kavi/blob/main/lib/agent-system-prompt.ts"
click node_language_detect "https://github.com/tehan-hewage/kavi/blob/main/lib/language-detect.ts"
click node_mcp_tools "https://github.com/tehan-hewage/kavi/blob/main/lib/mcp-tools.ts"
click node_mcp_client "https://github.com/tehan-hewage/kavi/blob/main/lib/mcp-client.ts"
click node_kapruka_mcp "https://github.com/tehan-hewage/kavi/blob/main/lib/kapruka-mcp.ts"
click node_voice_button "https://github.com/tehan-hewage/kavi/blob/main/components/voice/VoiceButton.tsx"
click node_voice_waveform "https://github.com/tehan-hewage/kavi/blob/main/components/voice/VoiceWaveform.tsx"
click node_use_voice "https://github.com/tehan-hewage/kavi/blob/main/hooks/useVoice.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_page,node_chat_shell,node_chat_input,node_message_list toneBlue
class node_cart_provider,node_language_provider,node_currency_provider,node_theme_provider toneAmber
class node_api_chat,node_api_product,node_api_speak,node_api_transcribe,node_api_voice_token toneMint
class node_agent_prompt,node_language_detect,node_mcp_tools,node_mcp_client,node_kapruka_mcp toneRose
class node_product_grid,node_product_card,node_product_modal,node_cart_drawer,node_cart_summary,node_checkout_form,node_pay_link toneIndigo
class node_voice_button,node_voice_waveform,node_use_voice toneTeal
```

## Components

### Browser UI

Full-screen shopping assistant experience composed from domain-specific panels and shared state.

- [Home](https://github.com/tehan-hewage/kavi/blob/main/app/page.tsx): Next.js entry · Main App Router page assembling the assistant experience. · `app/page.tsx`
- [Chat Shell](https://github.com/tehan-hewage/kavi/blob/main/components/chat/ChatShell.tsx): chat layout · Primary conversational container for the assistant UI. · `components/chat/ChatShell.tsx`
- [Chat Input](https://github.com/tehan-hewage/kavi/blob/main/components/chat/ChatInput.tsx): chat input · Composer for text prompts and user commands. · `components/chat/ChatInput.tsx`
- [Messages](https://github.com/tehan-hewage/kavi/blob/main/components/chat/MessageList.tsx): chat history · Conversation transcript and message rendering. · `components/chat/MessageList.tsx`

### Shared State

App-wide providers that synchronize language, currency, theme, and cart behavior.

- [Cart Provider](https://github.com/tehan-hewage/kavi/blob/main/components/providers/CartProvider.tsx): cart state · Client-side cart state shared across chat, cart, and checkout. · `components/providers/CartProvider.tsx`
- [Language Provider](https://github.com/tehan-hewage/kavi/blob/main/components/providers/LanguageProvider.tsx): i18n state · Global language selection and localization state. · `components/providers/LanguageProvider.tsx`
- [Currency Provider](https://github.com/tehan-hewage/kavi/blob/main/components/providers/CurrencyProvider.tsx): money state · Shared price-display and currency formatting state. · `components/providers/CurrencyProvider.tsx`
- [Theme Provider](https://github.com/tehan-hewage/kavi/blob/main/components/providers/ThemeProvider.tsx): theme state · Dark/light mode state used across the UI. · `components/providers/ThemeProvider.tsx`

### Next.js API

Server routes that bridge the browser to AI, catalog, and voice services.

- [Chat API](https://github.com/tehan-hewage/kavi/blob/main/app/api/chat/route.ts): agent route · Server boundary for AI shopping conversations. · `app/api/chat/route.ts`
- [Product API](https://github.com/tehan-hewage/kavi/blob/main/app/api/product/route.ts): catalog route · Server boundary for catalog and product lookup. · `app/api/product/route.ts`
- [Speak API](https://github.com/tehan-hewage/kavi/blob/main/app/api/speak/route.ts): tts route · Text-to-speech endpoint for voice playback. · `app/api/speak/route.ts`
- [Transcribe API](https://github.com/tehan-hewage/kavi/blob/main/app/api/transcribe/route.ts): stt route · Speech-to-text endpoint for audio capture uploads. · `app/api/transcribe/route.ts`
- [Voice Token](https://github.com/tehan-hewage/kavi/blob/main/app/api/voice/token/route.ts): auth route · Token exchange for external voice service access. · `app/api/voice/token/route.ts`

### AI Orchestration

Prompting, language handling, and MCP tool integration for the shopping agent.

- [Agent Prompt](https://github.com/tehan-hewage/kavi/blob/main/lib/agent-system-prompt.ts): system prompt · Core shopping-agent instructions and response shaping. · `lib/agent-system-prompt.ts`
- [Language Detect](https://github.com/tehan-hewage/kavi/blob/main/lib/language-detect.ts): language logic · Language and script detection used to steer responses. · `lib/language-detect.ts`
- [MCP Tools](https://github.com/tehan-hewage/kavi/blob/main/lib/mcp-tools.ts): tooling layer · Tool definitions and execution bridge for live commerce actions. · `lib/mcp-tools.ts`
- [MCP Client](https://github.com/tehan-hewage/kavi/blob/main/lib/mcp-client.ts): mcp client · Client wrapper for communicating with the MCP server. · `lib/mcp-client.ts`
- [Kapruka MCP](https://github.com/tehan-hewage/kavi/blob/main/lib/kapruka-mcp.ts): commerce backend · External commerce source for live catalog and availability data. · `lib/kapruka-mcp.ts`

### Commerce UI

Product, cart, and checkout surfaces that turn chat intent into purchase flow.

- [Product Grid](https://github.com/tehan-hewage/kavi/blob/main/components/products/ProductGrid.tsx): catalog view · Browseable product results surfaced from agent or catalog lookups. · `components/products/ProductGrid.tsx`
- [Product Card](https://github.com/tehan-hewage/kavi/blob/main/components/products/ProductCard.tsx): product tile · Compact product presentation used in lists and recommendations. · `components/products/ProductCard.tsx`
- [Detail Modal](https://github.com/tehan-hewage/kavi/blob/main/components/products/ProductDetailModal.tsx): product detail · Expanded product view for inspection and selection. · `components/products/ProductDetailModal.tsx`
- [Cart Drawer](https://github.com/tehan-hewage/kavi/blob/main/components/cart/CartDrawer.tsx): cart panel · Side cart surface for reviewing and editing items. · `components/cart/CartDrawer.tsx`
- [Cart Summary](https://github.com/tehan-hewage/kavi/blob/main/components/cart/CartSummary.tsx): pricing summary · Totals and purchase summary for the active cart. · `components/cart/CartSummary.tsx`
- [Checkout Form](https://github.com/tehan-hewage/kavi/blob/main/components/checkout/CheckoutForm.tsx): checkout flow · Checkout fields for delivery, gifts, and order finalization. · `components/checkout/CheckoutForm.tsx`
- [Pay Link](https://github.com/tehan-hewage/kavi/blob/main/components/checkout/PayLinkCard.tsx): payment prompt · Payment CTA and urgency card for completing checkout. · `components/checkout/PayLinkCard.tsx`

### Voice Pipeline

Capture, transcribe, synthesize, and render voice interactions.

- [Voice Button](https://github.com/tehan-hewage/kavi/blob/main/components/voice/VoiceButton.tsx): voice control · Entry point for push-to-talk or voice mode interaction. · `components/voice/VoiceButton.tsx`
- [Waveform](https://github.com/tehan-hewage/kavi/blob/main/components/voice/VoiceWaveform.tsx): voice visualizer · Animated visual feedback for active voice sessions. · `components/voice/VoiceWaveform.tsx`
- [Use Voice](https://github.com/tehan-hewage/kavi/blob/main/hooks/useVoice.ts): voice hook · Client voice-state controller connecting capture and playback. · `hooks/useVoice.ts`

## Connections

- Home → Chat Shell: assembles · Home page composes the conversational shell and supporting panels.
- Home → Product Grid: shows · Main experience can surface product discovery alongside chat.
- Home → Cart Drawer: includes · Cart is available as part of the single-screen shopping flow.
- Home → Checkout Form: includes · Checkout is embedded in the same UI rather than a separate route.
- Home → Voice Button: enables · Voice interaction is exposed from the main app surface.
- Chat Shell → Chat Input: contains · The shell hosts the message composer.
- Chat Shell → Messages: contains · The shell renders the conversation history.
- Cart Provider → Cart Drawer: drives · Shared cart state powers the drawer contents.
- Cart Provider → Cart Summary: drives · Totals and item counts derive from cart state.
- Currency Provider → Product Card: formats · Currency state affects displayed prices in product views.
- Language Provider → Chat Shell: localizes · Language state changes chat copy and response language.
- Theme Provider → Home: themes · Theme state controls global light/dark rendering.
- Chat API → Agent Prompt: uses · Chat route applies the agent system prompt.
- Chat API → Language Detect: detects · Incoming chat messages are normalized by language/script.
- Chat API → MCP Tools: invokes · Chat backend can call commerce tools for live actions.
- MCP Tools → MCP Client: wraps · Tool layer delegates transport to the MCP client.
- MCP Client → Kapruka MCP: connects · Client reaches the external Kapruka MCP service.
- Product API → MCP Tools: queries · Product lookups route through the same commerce tooling boundary.
- Speak API → Voice Button: supports · Speech synthesis feeds voice playback flows.
- Transcribe API → Use Voice: supports · Transcription is part of the voice capture pipeline.
- Voice Token → Use Voice: authorizes · Voice token exchange enables external voice sessions.
- Use Voice → Waveform: renders · Voice state drives the active waveform visualization.
- Use Voice → Voice Button: controls · Hook coordinates recording, playback, and mute state.
- Product Grid → Product Card: contains · Grid is composed of repeated product cards.
- Product Card → Detail Modal: opens · Card interactions can reveal the detail modal.
- Cart Drawer → Checkout Form: feeds · Selected cart items flow into checkout.
- Checkout Form → Pay Link: ends with · Checkout culminates in the payment prompt/card.