tehan-hewage/kavi

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.