# cookie-cat21/kira architecture

> Architecture diagram of the GitHub repository cookie-cat21/kira, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cookie-cat21/kira
- Repository: https://github.com/cookie-cat21/kira

## Overview

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: [`lib/kira/context.ts`](https://github.com/cookie-cat21/kira/blob/main/lib/kira/context.ts) (Kira core), [`app/layout.tsx`](https://github.com/cookie-cat21/kira/blob/main/app/layout.tsx) (App shell), [`app/components/KiraExperience.tsx`](https://github.com/cookie-cat21/kira/blob/main/app/components/KiraExperience.tsx) (Assistant UI), [`app/components/store/StoreChrome.tsx`](https://github.com/cookie-cat21/kira/blob/main/app/components/store/StoreChrome.tsx) (Store UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main_app["Kira app"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_home_page["Landing<br/>route page<br/>[page.tsx]"]
  node_shop_page["Shop<br/>route page<br/>[page.tsx]"]
  node_product_pages["Products<br/>route pages<br/>[page.tsx]"]
  node_kira_page["Kira chat<br/>route page<br/>[page.tsx]"]
  node_demo_pages["Demos<br/>route pages<br/>[page.tsx]"]
  node_store_ui["Store UI<br/>storefront components<br/>[StoreChrome.tsx]"]
  node_assistant_ui["Assistant UI<br/>chat components<br/>[KiraExperience.tsx]"]
  node_glass_ui["Glass kit<br/>design system<br/>[index.ts]"]
  node_cart_state(("Cart state<br/>client context<br/>[CartContext.tsx]"))
  node_dock_state(("Dock state<br/>client context"))
  node_reorder_memory[("Last order<br/>browser storage")]
end

subgraph group_core_ai["Kira brain"]
  node_api_chat["Chat API<br/>route handler<br/>[route.ts]"]
  node_api_checkout["Checkout API<br/>route handler<br/>[route.ts]"]
  node_api_store["Commerce APIs<br/>route handlers<br/>[route.ts]"]
  node_api_health["Health APIs<br/>route handlers<br/>[route.ts]"]
  node_kira_core["Kira core<br/>agent orchestration<br/>[context.ts]"]
  node_search_routing["Search routing<br/>search orchestration<br/>[search-routing.ts]"]
  node_groq_client["Groq<br/>llm client<br/>[groq.ts]"]
  node_mcp_bridge["MCP bridge<br/>integration client<br/>[mcp-client.ts]"]
  node_local_catalog[("Local catalog<br/>seeded commerce data<br/>[seed-catalog.json]")]
  node_policy_guard["Policy guard<br/>middleware/rate limit<br/>[middleware.ts]"]
end

subgraph group_ops["Ops"]
  node_e2e_tests["E2E tests<br/>playwright suite<br/>[kira.spec.ts]"]
  node_automation["Automation<br/>orchestration scripts<br/>[test-suite.mjs]"]
  node_workflows["CI workflows<br/>github actions<br/>[e2e.yml]"]
end

subgraph group_leak_system["claude-code-leak"]
  node_leak_root["Leak project<br/>separate project<br/>[package.json]"]
end

node_app_shell -->|"wraps"| node_home_page
node_app_shell -->|"wraps"| node_shop_page
node_app_shell -->|"wraps"| node_product_pages
node_app_shell -->|"wraps"| node_kira_page
node_app_shell -->|"wraps"| node_demo_pages
node_home_page -->|"renders"| node_store_ui
node_shop_page -->|"renders"| node_store_ui
node_product_pages -->|"renders"| node_store_ui
node_kira_page -->|"renders"| node_assistant_ui
node_store_ui -->|"shares primitives"| node_glass_ui
node_assistant_ui -->|"shares primitives"| node_glass_ui
node_assistant_ui -->|"reads/writes"| node_cart_state
node_assistant_ui -->|"reads/writes"| node_dock_state
node_assistant_ui -->|"persists"| node_reorder_memory
node_reorder_memory -->|"feeds"| node_api_checkout
node_api_chat -->|"delegates to"| node_kira_core
node_api_checkout -->|"delegates to"| node_kira_core
node_api_store -->|"serves data"| node_local_catalog
node_api_health -->|"reports"| node_mcp_bridge
node_kira_core -->|"routes search"| node_search_routing
node_kira_core -->|"calls"| node_groq_client
node_kira_core -->|"calls"| node_mcp_bridge
node_kira_core -->|"constrained by"| node_policy_guard
node_policy_guard -->|"protects"| node_api_chat
node_policy_guard -->|"protects"| node_api_checkout
node_e2e_tests -->|"exercises"| node_api_chat
node_e2e_tests -->|"exercises"| node_api_checkout
node_automation -->|"drives"| node_e2e_tests
node_workflows -->|"runs"| node_automation
node_leak_root -.->|"separate system"| node_api_chat

click node_app_shell "https://github.com/cookie-cat21/kira/blob/main/app/layout.tsx"
click node_home_page "https://github.com/cookie-cat21/kira/blob/main/app/page.tsx"
click node_shop_page "https://github.com/cookie-cat21/kira/blob/main/app/shop/page.tsx"
click node_product_pages "https://github.com/cookie-cat21/kira/blob/main/app/shop/[slug]/page.tsx"
click node_kira_page "https://github.com/cookie-cat21/kira/blob/main/app/kira/page.tsx"
click node_demo_pages "https://github.com/cookie-cat21/kira/blob/main/app/liquid-glass/page.tsx"
click node_store_ui "https://github.com/cookie-cat21/kira/blob/main/app/components/store/StoreChrome.tsx"
click node_assistant_ui "https://github.com/cookie-cat21/kira/blob/main/app/components/KiraExperience.tsx"
click node_glass_ui "https://github.com/cookie-cat21/kira/blob/main/app/components/glass/index.ts"
click node_cart_state "https://github.com/cookie-cat21/kira/blob/main/app/context/CartContext.tsx"
click node_dock_state "https://github.com/cookie-cat21/kira/blob/main/app/context/KiraDockContext.tsx"
click node_reorder_memory "https://github.com/cookie-cat21/kira/blob/main/lib/last-order-storage.ts"
click node_api_chat "https://github.com/cookie-cat21/kira/blob/main/app/api/chat/route.ts"
click node_api_checkout "https://github.com/cookie-cat21/kira/blob/main/app/api/checkout/route.ts"
click node_api_store "https://github.com/cookie-cat21/kira/blob/main/app/api/store/products/route.ts"
click node_api_health "https://github.com/cookie-cat21/kira/blob/main/app/api/health/route.ts"
click node_kira_core "https://github.com/cookie-cat21/kira/blob/main/lib/kira/context.ts"
click node_search_routing "https://github.com/cookie-cat21/kira/blob/main/lib/kira/search-routing.ts"
click node_groq_client "https://github.com/cookie-cat21/kira/blob/main/lib/kira/groq.ts"
click node_mcp_bridge "https://github.com/cookie-cat21/kira/blob/main/lib/mcp-client.ts"
click node_local_catalog "https://github.com/cookie-cat21/kira/blob/main/data/seed-catalog.json"
click node_policy_guard "https://github.com/cookie-cat21/kira/blob/main/middleware.ts"
click node_e2e_tests "https://github.com/cookie-cat21/kira/blob/main/tests/e2e/kira.spec.ts"
click node_automation "https://github.com/cookie-cat21/kira/blob/main/scripts/test-suite.mjs"
click node_workflows "https://github.com/cookie-cat21/kira/blob/main/.github/workflows/e2e.yml"
click node_leak_root "https://github.com/cookie-cat21/kira/blob/main/claude-code-leak/package.json"

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_shell,node_home_page,node_shop_page,node_product_pages,node_kira_page,node_demo_pages,node_store_ui,node_assistant_ui,node_glass_ui,node_cart_state,node_dock_state,node_reorder_memory toneBlue
class node_api_chat,node_api_checkout,node_api_store,node_api_health,node_kira_core,node_search_routing,node_groq_client,node_mcp_bridge,node_local_catalog,node_policy_guard toneAmber
class node_e2e_tests,node_automation,node_workflows toneMint
class node_leak_root toneRose
```

## Components

### Kira app

Primary Next.js storefront and assistant runtime.

- [App shell](https://github.com/cookie-cat21/kira/blob/main/app/layout.tsx): Next.js layout · Global layout and shared app chrome for the root app. · `app/layout.tsx`
- [Landing](https://github.com/cookie-cat21/kira/blob/main/app/page.tsx): route page · Home page and welcome-back entry surface. · `app/page.tsx`
- [Shop](https://github.com/cookie-cat21/kira/blob/main/app/shop/page.tsx): route page · Primary storefront browsing surface. · `app/shop/page.tsx`
- [Products](https://github.com/cookie-cat21/kira/blob/main/app/shop/[slug]/page.tsx): route pages · Category, slug, and product detail routes for browsing and selection. · `app/shop/[slug]/page.tsx`
- [Kira chat](https://github.com/cookie-cat21/kira/blob/main/app/kira/page.tsx): route page · Assistant and conversational shopping surface. · `app/kira/page.tsx`
- [Demos](https://github.com/cookie-cat21/kira/blob/main/app/liquid-glass/page.tsx): route pages · Visual showcase routes for liquid-glass and orb demos. · `app/liquid-glass/page.tsx`
- [Store UI](https://github.com/cookie-cat21/kira/blob/main/app/components/store/StoreChrome.tsx): storefront components · Store-specific chrome, rails, landing sections, and product presentation. · `app/components/store/StoreChrome.tsx`
- [Assistant UI](https://github.com/cookie-cat21/kira/blob/main/app/components/KiraExperience.tsx): chat components · Chat, cart, product, and assistant interaction components. · `app/components/KiraExperience.tsx`
- [Glass kit](https://github.com/cookie-cat21/kira/blob/main/app/components/glass/index.ts): design system · Shared liquid-glass and low-level UI primitives. · `app/components/glass/index.ts`
- [Cart state](https://github.com/cookie-cat21/kira/blob/main/app/context/CartContext.tsx): client context · Client-side cart and checkout interaction state. · `app/context/CartContext.tsx`
- [Dock state](https://github.com/cookie-cat21/kira/blob/main/app/context/KiraDockContext.tsx): client context · Assistant dock and launcher state. · `app/context/KiraDockContext.tsx`
- [Last order](https://github.com/cookie-cat21/kira/blob/main/lib/last-order-storage.ts): browser storage · 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](https://github.com/cookie-cat21/kira/blob/main/app/api/chat/route.ts): route handler · Conversational assistant entrypoint. · `app/api/chat/route.ts`
- [Checkout API](https://github.com/cookie-cat21/kira/blob/main/app/api/checkout/route.ts): route handler · Guest checkout orchestration endpoint. · `app/api/checkout/route.ts`
- [Commerce APIs](https://github.com/cookie-cat21/kira/blob/main/app/api/store/products/route.ts): route handlers · Commerce lookup, product, category, search, and delivery endpoints. · `app/api/store/products/route.ts`
- [Health APIs](https://github.com/cookie-cat21/kira/blob/main/app/api/health/route.ts): route handlers · Health and MCP status endpoints used for service monitoring. · `app/api/health/route.ts`
- [Kira core](https://github.com/cookie-cat21/kira/blob/main/lib/kira/context.ts): agent orchestration · Prompt assembly, routing, SSE streaming, sanitization, and checkout logic. · `lib/kira/context.ts`
- [Search routing](https://github.com/cookie-cat21/kira/blob/main/lib/kira/search-routing.ts): search orchestration · Fast-path search and product discovery routing. · `lib/kira/search-routing.ts`
- [Groq](https://github.com/cookie-cat21/kira/blob/main/lib/kira/groq.ts): llm client · LLM inference and model fallback layer. · `lib/kira/groq.ts`
- [MCP bridge](https://github.com/cookie-cat21/kira/blob/main/lib/mcp-client.ts): integration client · Client and parsing bridge to Kapruka MCP live commerce actions. · `lib/mcp-client.ts`
- [Local catalog](https://github.com/cookie-cat21/kira/blob/main/data/seed-catalog.json): seeded commerce data · Schema-backed seeded catalog used for local browsing and fallback. · `data/seed-catalog.json`
- [Policy guard](https://github.com/cookie-cat21/kira/blob/main/middleware.ts): middleware/rate limit · Request-level policy, throttling, and assistant action gating. · `middleware.ts`

### Ops

Validation, testing, and automation.

- [E2E tests](https://github.com/cookie-cat21/kira/blob/main/tests/e2e/kira.spec.ts): playwright suite · Browser validation for chat, checkout, and reorder flows. · `tests/e2e/kira.spec.ts`
- [Automation](https://github.com/cookie-cat21/kira/blob/main/scripts/test-suite.mjs): orchestration scripts · QA, persona, regression, and evaluation scripts. · `scripts/test-suite.mjs`
- [CI workflows](https://github.com/cookie-cat21/kira/blob/main/.github/workflows/e2e.yml): github actions · Validation and release workflows. · `.github/workflows/e2e.yml`

### claude-code-leak

Separate self-contained secondary project subtree.

- [Leak project](https://github.com/cookie-cat21/kira/blob/main/claude-code-leak/package.json): separate project · Self-contained secondary codebase with its own web, CLI, MCP, and runtime layers. · `claude-code-leak/package.json`

## Connections

- 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.
