rasaljayasinghe/nayana-kapruka

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.