How cookie-cat21/kira works
1. Top-level shape
- This repo is a single Next.js 16 app at the root, written in TypeScript and styled with Tailwind v4.
- It is deployed as a full-stack Vercel app: the same codebase serves the UI, server-rendered pages, and API route handlers.
2. Primary product surface
- The main user-facing experience is Kira, an AI shopping companion for Kapruka.
- The app exposes separate route surfaces for:
- the shopping storefront (/shop, /shop/[slug], /product/[id])
- the assistant/chat experience (/kira)
- the home/landing page (/)
- a couple of visual demo routes (/liquid-glass, /demo/kira-orb).
3. UI composition boundaries
- Presentation is split into three clear component families:
- storefront components under app/components/store
- assistant/chat components under app/components
- a shared glass/design-system layer under app/components/glass and app/components/ui
- This matters architecturally because the storefront and the assistant share styling primitives, but their behavior and state flows are different.
4. Client state and interaction state
- Interactive state is mostly client-side React state with explicit contexts:
- app/context/CartContext.tsx for commerce/cart state
- app/context/KiraDockContext.tsx for the assistant dock/launcher experience
- Reorder memory is persisted in the browser via lib/last-order-storage.ts, which enables the “welcome back” and “order again” flows without requiring account login.
5. Server-side API boundary
- The app uses Next.js route handlers in app/api/* as the server boundary.
- The important endpoints are:
- app/api/chat — the conversational agent entrypoint
- app/api/checkout — guest checkout orchestration
- app/api/delivery-cities, app/api/products/[id], app/api/store/* — commerce data and lookup endpoints
- app/api/mcp-status and app/api/health — service health and integration status
- These endpoints are the bridge between the UI and the external commerce/AI systems.
6. Agent orchestration layer
- The core Kira intelligence lives in lib/kira/*.
- This layer contains the agent’s:
- prompt/context assembly
- fast-path routing
- checkout flow logic
- search routing
- SSE streaming
- response sanitization
- permissions and out-of-scope handling
- In diagram terms, this is the application brain between /api/chat and external services.
7. External integrations
- Two integrations materially define the architecture:
- Groq API for LLM inference, with model/fallback logic in the Kira layer
- Kapruka MCP (https://mcp.kapruka.com/mcp) for live product search, delivery quotes, and checkout actions
- The MCP client/parsing helpers in lib/mcp-client.ts, lib/mcp-parsing.ts, and related Kira modules are the main bridge to Kapruka’s live capabilities.
8. Commerce data and lookup paths
- The repo includes a local commerce substrate:
- data/seed-catalog.json
- db/schema.sql
- lib/catalog.ts, lib/db.ts, types/store.ts
- That suggests a local catalog/schema layer used for browsing, fallback, or seeded data, while the live Kapruka MCP provides real-time product and delivery operations.
- Search and product discovery are further routed through Kira helpers such as lib/kira/search.ts, lib/kira/search-routing.ts, and lib/kira/fast-paths.ts.
9. Request policy and cross-cutting controls
- Cross-cutting concerns are handled outside the main UI flow:
- middleware.ts for request-level policy
- lib/rate-limit.ts for endpoint protection
- lib/kira/permissions.ts and related modules for tool/action gating
- These form the safety and control boundary around the assistant and commerce actions.
10. Reorder loop
- The repository explicitly supports a returning-customer reorder loop:
- checkout success writes the last order
- the landing page can surface a welcome back strip
- chat can trigger “order again”
- reorder can land directly in checkout review
- Architecturally, this is a closed loop between UI state, browser persistence, and the checkout flow.
11. Testing and release automation
- Runtime and quality assurance are backed by:
- Playwright E2E tests in tests/e2e
- GitHub Actions workflows in .github/workflows
- a large set of orchestration/evaluation scripts under scripts/
- These scripts are not part of production runtime, but they are a major operational boundary for validation, persona testing, live regression, and submission gating.
12. Important separate subtree
- The claude-code-leak/ directory is effectively a second, much larger self-contained project with its own src/, web/, mcp-server/, docs, scripts, and CI.
- It should be treated as a separate bounded system in any architecture diagram unless you intentionally want a repo-inventory view; it does not appear to be the core Kira storefront/runtime.
13. How the main data flow looks
- Typical flow is:
- user enters the storefront or chat UI
- client components update local state/context
- chat or checkout actions hit Next.js API routes
- lib/kira orchestrates the request
- Groq generates assistant behavior
- Kapruka MCP resolves live commerce actions
- results stream back to the client, with selected state persisted locally for reorder continuity
Main entry points: context.ts Kira core · layout.tsx App shell · KiraExperience.tsx Assistant UI · StoreChrome.tsx Store UI
Components 26
Kira app
Primary Next.js storefront and assistant runtime.
- App shell · Global layout and shared app chrome for the root app.
app/layout.tsx - Landing · Home page and welcome-back entry surface.
app/page.tsx - Shop · Primary storefront browsing surface.
app/shop/page.tsx - Products · Category, slug, and product detail routes for browsing and selection.
app/shop/[slug]/page.tsx - Kira chat · Assistant and conversational shopping surface.
app/kira/page.tsx - Demos · Visual showcase routes for liquid-glass and orb demos.
app/liquid-glass/page.tsx - Store UI · Store-specific chrome, rails, landing sections, and product presentation.
app/components/store/StoreChrome.tsx - Assistant UI · Chat, cart, product, and assistant interaction components.
app/components/KiraExperience.tsx - Glass kit · Shared liquid-glass and low-level UI primitives.
app/components/glass/index.ts - Cart state · Client-side cart and checkout interaction state.
app/context/CartContext.tsx - Dock state · Assistant dock and launcher state.
app/context/KiraDockContext.tsx - Last order · Persisted reorder memory for welcome-back and order-again flows.
lib/last-order-storage.ts
Kira brain
Assistant orchestration, commerce lookup, and integration layer.
- Chat API · Conversational assistant entrypoint.
app/api/chat/route.ts - Checkout API · Guest checkout orchestration endpoint.
app/api/checkout/route.ts - Commerce APIs · Commerce lookup, product, category, search, and delivery endpoints.
app/api/store/products/route.ts - Health APIs · Health and MCP status endpoints used for service monitoring.
app/api/health/route.ts - Kira core · Prompt assembly, routing, SSE streaming, sanitization, and checkout logic.
lib/kira/context.ts - Search routing · Fast-path search and product discovery routing.
lib/kira/search-routing.ts - Groq · LLM inference and model fallback layer.
lib/kira/groq.ts - MCP bridge · Client and parsing bridge to Kapruka MCP live commerce actions.
lib/mcp-client.ts - Local catalog · Schema-backed seeded catalog used for local browsing and fallback.
data/seed-catalog.json - Policy guard · Request-level policy, throttling, and assistant action gating.
middleware.ts
Ops
Validation, testing, and automation.
- E2E tests · Browser validation for chat, checkout, and reorder flows.
tests/e2e/kira.spec.ts - Automation · QA, persona, regression, and evaluation scripts.
scripts/test-suite.mjs - CI workflows · Validation and release workflows.
.github/workflows/e2e.yml
claude-code-leak
Separate self-contained secondary project subtree.
- Leak project · Self-contained secondary codebase with its own web, CLI, MCP, and runtime layers.
claude-code-leak/package.json
Connections 30
- App shell → Landing: wraps · The global shell wraps the landing route.
- App shell → Shop: wraps · The global shell wraps the storefront route.
- App shell → Products: wraps · The global shell wraps product detail routes.
- App shell → Kira chat: wraps · The global shell wraps the assistant route.
- App shell → Demos: wraps · The global shell also wraps demo routes.
- Landing → Store UI: renders · Landing page composes store-facing UI modules.
- Shop → Store UI: renders · Shop page uses storefront components.
- Products → Store UI: renders · Product views use storefront components.
- Kira chat → Assistant UI: renders · Assistant page composes chat and commerce interaction UI.
- Store UI → Glass kit: shares primitives · Storefront UI reuses the shared glass/design system layer.
- Assistant UI → Glass kit: shares primitives · Assistant UI also reuses the shared glass/design system layer.
- Assistant UI → Cart state: reads/writes · Commerce interactions are coordinated through cart state.
- Assistant UI → Dock state: reads/writes · Assistant launcher and dock behavior are controlled by dock state.
- Assistant UI → Last order: persists · Returning-customer flows persist last-order memory in the browser.
- Last order → Checkout API: feeds · Stored last-order data can shortcut users into checkout.
- Chat API → Kira core: delegates to · Chat requests are orchestrated by the Kira core layer.
- Checkout API → Kira core: delegates to · Checkout requests use the same orchestration layer.
- Commerce APIs → Local catalog: serves data · Store APIs can serve from the seeded local catalog substrate.
- Health APIs → MCP bridge: reports · Health/status routes surface MCP integration state.
- Kira core → Search routing: routes search · Kira core routes search and product discovery intents.
- Kira core → Groq: calls · LLM generation is handled through Groq.
- Kira core → MCP bridge: calls · Live commerce actions are bridged through Kapruka MCP.
- Kira core → Policy guard: constrained by · Permissions, rate limits, and request policy gate assistant actions.
- Policy guard → Chat API: protects · Request policy protects the chat endpoint.
- Policy guard → Checkout API: protects · Request policy protects checkout actions.
- E2E tests → Chat API: exercises · E2E tests validate assistant chat behavior.
- E2E tests → Checkout API: exercises · E2E tests validate checkout and reorder flows.
- Automation → E2E tests: drives · Automation scripts orchestrate test and regression runs.
- CI workflows → Automation: runs · CI workflows invoke repository automation.
- Leak project → Chat API: separate system · Secondary subtree is architecturally distinct from the main Kira app.