# sethum-vs/agentickapruka architecture

> Architecture diagram of the GitHub repository sethum-vs/agentickapruka, 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/sethum-vs/agentickapruka
- Repository: https://github.com/sethum-vs/agentickapruka

## Overview

1. **Overall shape**
   - This repo is a Python 3.12+ FastAPI application that serves a server-rendered, chat-first shopping experience for Kapruka.
   - The architecture is split into: browser UI, HTTP/app layer, LangGraph orchestration, and external data/memory services.

2. **Client/UI boundary**
   - The browser talks mainly through HTMX-driven HTML fragments and Server-Sent Events, not a SPA API.
   - Core UI surfaces are the chat page, cart drawer, checkout forms, and small reusable partials under `templates/` plus client scripts in `static/js/`.

3. **FastAPI application layer**
   - `app/main.py` mounts route modules for chat, cart, checkout, session, partials, dev, and health.
   - `app/lifespan.py` manages startup/shutdown for the service dependencies, while `app/middleware/errors.py` centralizes error handling.
   - This layer is the boundary between HTTP requests and the agent/workflow logic.

4. **Chat request pipeline**
   - The main conversational flow is in `graphs/shopping_graph.py` and its nodes.
   - Each message is classified by intent, supervised by `master_flow`, then routed into one of a few paths: discovery, cart actions, checkout, tracking, or general/support.
   - Responses are streamed back to the browser, which is why chat feels incremental rather than request/response only.

5. **Discovery and retrieval path**
   - Shopping discovery uses a hybrid retrieval stack: query preprocessing, intent/specificity gating, Neo4j-based context expansion, and Zep memory for preferences.
   - `graphs/nodes/retrieve_hybrid_context.py` and related helpers in `lib/neo4j/` and `lib/zep/` shape the search context before any live Kapruka tools are called.
   - The design keeps vague requests from hitting the catalog blindly; the assistant may ask clarifying questions first.

6. **Bounded agent loop**
   - After retrieval, the shopping graph enters a bounded agent loop that can call Kapruka tools, inspect results, and then generate a final answer.
   - Product curation logic in `lib/chat/` filters and ranks results so the UI shows gift-relevant items rather than raw catalog output.
   - The loop is intentionally capped, which keeps browsing deterministic enough for a chat commerce flow.

7. **Checkout as a separate deterministic workflow**
   - Checkout is not handled by the same open-ended shopping loop; it has its own LangGraph in `graphs/checkout_graph.py`.
   - The checkout path is stepwise and ordered: cart, delivery city, delivery date, recipient, sender, review, finalize.
   - State is persisted in Redis so the user can move through forms without losing progress, and the review/finalization steps are more controlled than discovery.

8. **Live commerce integration**
   - All live product, delivery, and order actions go through the Kapruka MCP service abstraction in `lib/kapruka/`.
   - The MCP client/tool executor wraps functions like search, get product, delivery validation, order creation, and tracking.
   - This is the main boundary to the external commerce system; the app does not directly embed product data.

9. **Data and memory layer**
   - Redis is the operational state store: sessions, cart, checkout state, cache, rate limiting, and LangGraph checkpointer behavior.
   - Neo4j holds the gift/category ontology and vector-searchable graph context used for GraphRAG-style retrieval and recommendations.
   - Zep provides longer-term conversational memory and customer preferences across sessions.

10. **Model and AI routing**
   - Google Vertex AI Gemini powers intent classification and response generation.
   - Model routing in `graphs/model_router.py` and `lib/chat/model_router.py` chooses lighter or heavier models depending on task complexity, with more capable models reserved for complex checkout/review turns.
   - Embeddings also come from Vertex AI and feed the Neo4j hybrid retrieval pipeline.

11. **Recommendations and background analytics**
   - There is a separate analytics path under `lib/analytics/` that computes co-purchase communities using NetworkX, with an optional cuGraph path for GPU/local use.
   - The output is written back into Neo4j as recommendation relationships, so recommendation generation is batch/background work rather than part of every chat turn.

12. **Operational boundaries**
   - `/health` aggregates dependency state across Redis, Neo4j, Zep, and the Kapruka MCP endpoint.
   - Deployment is containerized with Docker and targeted at Google Cloud Run, with Gunicorn used for serving in production.
   - The repo also includes dedicated evals and a large test suite, which act as a quality boundary for the agent flows, checkout state machine, and integration with external services.

Main entry points: [`app/main.py`](https://github.com/sethum-vs/agentickapruka/blob/main/app/main.py) (App entry), [`graphs/shopping_graph.py`](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/shopping_graph.py) (Shopping graph), [`lib/redis`](https://github.com/sethum-vs/agentickapruka/tree/main/lib/redis) (Redis state), [`graphs/checkout_graph.py`](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/checkout_graph.py) (Checkout graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_templates_chat["Chat views<br/>SSR templates"]
  node_templates_checkout["Checkout views<br/>SSR templates"]
  node_templates_components["UI parts<br/>partials/templates"]
  node_static_js["Client scripts<br/>browser JS"]
end

subgraph group_app["HTTP App"]
  node_app_main["App entry<br/>FastAPI app<br/>[main.py]"]
  node_app_lifespan["Lifespan<br/>startup/shutdown<br/>[lifespan.py]"]
  node_app_middleware["Error middleware<br/>HTTP middleware<br/>[errors.py]"]
  node_routes_chat["Chat route<br/>HTTP routes<br/>[chat.py]"]
  node_routes_checkout["Checkout route<br/>HTTP routes<br/>[checkout.py]"]
  node_routes_cart["Cart route<br/>HTTP routes<br/>[cart.py]"]
end

subgraph group_graph["Agent Graphs"]
  node_shopping_graph{{"Shopping graph<br/>LangGraph<br/>[shopping_graph.py]"}}
  node_checkout_graph{{"Checkout graph<br/>LangGraph<br/>[checkout_graph.py]"}}
  node_master_flow["Master flow<br/>routing node<br/>[master_flow.py]"]
  node_retrieval_node["Hybrid context<br/>retrieval node"]
  node_agent_loop["Agent loop<br/>bounded loop<br/>[agent_loop.py]"]
  node_checkout_steps["Checkout steps<br/>state steps<br/>[checkout_steps.py]"]
end

subgraph group_services["Service Layer"]
  node_chat_lib["Chat logic<br/>service helpers"]
  node_checkout_lib["Checkout logic<br/>service helpers"]
  node_kapruka_service["Kapruka MCP<br/>commerce adapter"]
  node_neo4j_lib[("Neo4j graph<br/>retrieval store")]
  node_redis_lib[("Redis state<br/>state store")]
  node_zep_lib[("Zep memory<br/>long-term memory")]
  node_genai_lib["Gemini AI<br/>model client"]
  node_analytics_lib["Analytics"]
end

subgraph group_external["External Systems"]
  node_vertex_ai(("Vertex AI<br/>LLM/embeddings"))
  node_kapruka_mcp(("Kapruka MCP<br/>external commerce API"))
  node_neo4j_db[("Neo4j DB<br/>graph database")]
  node_redis_db[("Redis<br/>cache/state backend")]
  node_zep_service[("Zep<br/>memory backend")]
end

node_app_main -->|"mounts"| node_routes_chat
node_app_main -->|"mounts"| node_routes_cart
node_app_main -->|"mounts"| node_routes_checkout
node_app_main -->|"uses"| node_app_lifespan
node_app_main -->|"uses"| node_app_middleware
node_routes_chat -->|"runs"| node_shopping_graph
node_routes_checkout -->|"runs"| node_checkout_graph
node_routes_cart -->|"reads/writes"| node_redis_lib
node_shopping_graph -->|"routes through"| node_master_flow
node_shopping_graph -->|"retrieves context"| node_retrieval_node
node_shopping_graph -->|"continues with"| node_agent_loop
node_shopping_graph -->|"uses"| node_chat_lib
node_checkout_graph -->|"advances through"| node_checkout_steps
node_checkout_graph -->|"uses"| node_checkout_lib
node_retrieval_node -->|"queries"| node_neo4j_lib
node_retrieval_node -->|"loads memory"| node_zep_lib
node_agent_loop -->|"calls tools"| node_kapruka_service
node_agent_loop -->|"generates"| node_genai_lib
node_chat_lib -->|"routes models"| node_genai_lib
node_chat_lib -->|"uses"| node_redis_lib
node_checkout_lib -->|"persists"| node_redis_lib
node_kapruka_service -->|"bridges to"| node_kapruka_mcp
node_neo4j_lib -->|"stores/queries"| node_neo4j_db
node_redis_lib -->|"backed by"| node_redis_db
node_zep_lib -->|"backed by"| node_zep_service
node_genai_lib -->|"uses"| node_vertex_ai
node_analytics_lib -->|"writes"| node_neo4j_db
node_templates_chat -.->|"rendered by"| node_routes_chat
node_templates_checkout -.->|"rendered by"| node_routes_checkout
node_templates_components -.->|"shared with"| node_routes_cart
node_static_js -.->|"enhances"| node_templates_chat
node_static_js -.->|"enhances"| node_templates_checkout

click node_templates_chat "https://github.com/sethum-vs/agentickapruka/tree/main/templates/chat"
click node_templates_checkout "https://github.com/sethum-vs/agentickapruka/tree/main/templates/checkout"
click node_templates_components "https://github.com/sethum-vs/agentickapruka/tree/main/templates/components"
click node_static_js "https://github.com/sethum-vs/agentickapruka/tree/main/static/js"
click node_app_main "https://github.com/sethum-vs/agentickapruka/blob/main/app/main.py"
click node_app_lifespan "https://github.com/sethum-vs/agentickapruka/blob/main/app/lifespan.py"
click node_app_middleware "https://github.com/sethum-vs/agentickapruka/blob/main/app/middleware/errors.py"
click node_routes_chat "https://github.com/sethum-vs/agentickapruka/blob/main/app/routes/chat.py"
click node_routes_checkout "https://github.com/sethum-vs/agentickapruka/blob/main/app/routes/checkout.py"
click node_routes_cart "https://github.com/sethum-vs/agentickapruka/blob/main/app/routes/cart.py"
click node_shopping_graph "https://github.com/sethum-vs/agentickapruka/blob/main/graphs/shopping_graph.py"
click node_checkout_graph "https://github.com/sethum-vs/agentickapruka/blob/main/graphs/checkout_graph.py"
click node_master_flow "https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/master_flow.py"
click node_retrieval_node "https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/retrieve_hybrid_context.py"
click node_agent_loop "https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/agent_loop.py"
click node_checkout_steps "https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/checkout_steps.py"
click node_chat_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/chat"
click node_checkout_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/checkout"
click node_kapruka_service "https://github.com/sethum-vs/agentickapruka/tree/main/lib/kapruka"
click node_neo4j_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/neo4j"
click node_redis_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/redis"
click node_zep_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/zep"
click node_genai_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/genai"
click node_analytics_lib "https://github.com/sethum-vs/agentickapruka/tree/main/lib/analytics"

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_templates_chat,node_templates_checkout,node_templates_components,node_static_js toneBlue
class node_app_main,node_app_lifespan,node_app_middleware,node_routes_chat,node_routes_checkout,node_routes_cart toneAmber
class node_shopping_graph,node_checkout_graph,node_master_flow,node_retrieval_node,node_agent_loop,node_checkout_steps toneMint
class node_chat_lib,node_checkout_lib,node_kapruka_service,node_neo4j_lib,node_redis_lib,node_zep_lib,node_genai_lib,node_analytics_lib toneRose
class node_vertex_ai,node_kapruka_mcp,node_neo4j_db,node_redis_db,node_zep_service toneIndigo
```

## Components

### Browser UI

Server-rendered chat, cart, and checkout surfaces driven by HTMX and SSE.

- [Chat views](https://github.com/sethum-vs/agentickapruka/tree/main/templates/chat): SSR templates · Chat page, message fragments, and empty state rendered server-side. · `templates/chat`
- [Checkout views](https://github.com/sethum-vs/agentickapruka/tree/main/templates/checkout): SSR templates · Stepwise checkout forms, review screen, and tracking fragments. · `templates/checkout`
- [UI parts](https://github.com/sethum-vs/agentickapruka/tree/main/templates/components): partials/templates · Reusable cart, product, navigation, and status components. · `templates/components`
- [Client scripts](https://github.com/sethum-vs/agentickapruka/tree/main/static/js): browser JS · HTMX-adjacent helpers for chat, SSE, cart drawer, and countdown widgets. · `static/js`

### HTTP App

FastAPI entrypoints, routing, middleware, startup, and health boundary.

- [App entry](https://github.com/sethum-vs/agentickapruka/blob/main/app/main.py): FastAPI app · Creates the web application and mounts route modules. · `app/main.py`
- [Lifespan](https://github.com/sethum-vs/agentickapruka/blob/main/app/lifespan.py): startup/shutdown · Initializes and tears down service dependencies. · `app/lifespan.py`
- [Error middleware](https://github.com/sethum-vs/agentickapruka/blob/main/app/middleware/errors.py): HTTP middleware · Centralized request error handling and response shaping. · `app/middleware/errors.py`
- [Chat route](https://github.com/sethum-vs/agentickapruka/blob/main/app/routes/chat.py): HTTP routes · Chat turn handling, streaming responses, and chat page entry. · `app/routes/chat.py`
- [Checkout route](https://github.com/sethum-vs/agentickapruka/blob/main/app/routes/checkout.py): HTTP routes · Checkout form steps, review, finalize, and tracking endpoints. · `app/routes/checkout.py`
- [Cart route](https://github.com/sethum-vs/agentickapruka/blob/main/app/routes/cart.py): HTTP routes · Cart operations and drawer updates. · `app/routes/cart.py`

### Agent Graphs

LangGraph orchestration for shopping discovery and checkout.

- [Shopping graph](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/shopping_graph.py): LangGraph · Main conversational workflow for discovery, cart actions, tracking, and support. · `graphs/shopping_graph.py`
- [Checkout graph](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/checkout_graph.py): LangGraph · Deterministic checkout state machine for order completion. · `graphs/checkout_graph.py`
- [Master flow](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/master_flow.py): routing node · Classifies intent and selects the shopping path. · `graphs/nodes/master_flow.py`
- [Hybrid context](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/retrieve_hybrid_context.py): retrieval node · Builds query context with Neo4j expansion and Zep memory. · `graphs/nodes/retrieve_hybrid_context.py`
- [Agent loop](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/agent_loop.py): bounded loop · Calls commerce tools, inspects results, and prepares final responses. · `graphs/nodes/agent_loop.py`
- [Checkout steps](https://github.com/sethum-vs/agentickapruka/blob/main/graphs/nodes/checkout_steps.py): state steps · Ordered checkout progression across cart, delivery, recipient, sender, review, and finalize. · `graphs/nodes/checkout_steps.py`

### Service Layer

Chat helpers, commerce adapters, retrieval, memory, and persistence services.

- [Chat logic](https://github.com/sethum-vs/agentickapruka/tree/main/lib/chat): service helpers · Intent heuristics, routing, streaming, curation, prompts, and chat session utilities. · `lib/chat`
- [Checkout logic](https://github.com/sethum-vs/agentickapruka/tree/main/lib/checkout): service helpers · Form parsing, delivery validation, recipient/sender review, payment, and tracking helpers. · `lib/checkout`
- [Kapruka MCP](https://github.com/sethum-vs/agentickapruka/tree/main/lib/kapruka): commerce adapter · Tool executor and MCP client for live product, delivery, order, and tracking actions. · `lib/kapruka`
- [Neo4j graph](https://github.com/sethum-vs/agentickapruka/tree/main/lib/neo4j): retrieval store · Ontology, vector search, traversal, and hybrid context support. · `lib/neo4j`
- [Redis state](https://github.com/sethum-vs/agentickapruka/tree/main/lib/redis): state store · Sessions, cart, checkout, cache, rate limits, and LangGraph checkpointing. · `lib/redis`
- [Zep memory](https://github.com/sethum-vs/agentickapruka/tree/main/lib/zep): long-term memory · Conversation memory and user preference storage across sessions. · `lib/zep`
- [Gemini AI](https://github.com/sethum-vs/agentickapruka/tree/main/lib/genai): model client · Vertex AI client, fallback handling, and model routing support. · `lib/genai`
- [Analytics](https://github.com/sethum-vs/agentickapruka/tree/main/lib/analytics): batch analytics · Co-purchase community computation for recommendation relationships. · `lib/analytics`

### External Systems

Outside dependencies the app integrates with at runtime.

- **Vertex AI**: LLM/embeddings · Generates classifications, responses, and embeddings.
- **Kapruka MCP**: external commerce API · Live catalog, delivery, order creation, and tracking backend.
- **Neo4j DB**: graph database · Stores ontology, traversal context, and recommendation relationships.
- **Redis**: cache/state backend · Operational state, cache, rate limiting, and checkpoint persistence.
- **Zep**: memory backend · External memory service for long-term preferences.

## Connections

- App entry → Chat route: mounts · Registers chat endpoints and page handlers.
- App entry → Cart route: mounts · Registers cart endpoints.
- App entry → Checkout route: mounts · Registers checkout endpoints.
- App entry → Lifespan: uses · Starts and stops dependencies with the app.
- App entry → Error middleware: uses · Applies centralized error handling.
- Chat route → Shopping graph: runs · Delegates conversational shopping turns to the graph.
- Checkout route → Checkout graph: runs · Delegates checkout progression to the checkout graph.
- Cart route → Redis state: reads/writes · Persists cart state and session-linked data.
- Shopping graph → Master flow: routes through · Classifies intent and chooses the next path.
- Shopping graph → Hybrid context: retrieves context · Builds hybrid search context before tool use.
- Shopping graph → Agent loop: continues with · Executes bounded tool-driven shopping turns.
- Shopping graph → Chat logic: uses · Relies on chat heuristics, streaming, and curation helpers.
- Checkout graph → Checkout steps: advances through · Moves through the deterministic checkout sequence.
- Checkout graph → Checkout logic: uses · Uses form, review, payment, and tracking helpers.
- Hybrid context → Neo4j graph: queries · Expands context from graph ontology and vector search.
- Hybrid context → Zep memory: loads memory · Adds long-term preferences to retrieval context.
- Agent loop → Kapruka MCP: calls tools · Searches products, resolves details, and creates orders.
- Agent loop → Gemini AI: generates · Uses Gemini-based reasoning and response generation.
- Chat logic → Gemini AI: routes models · Selects lighter or heavier models by task complexity.
- Chat logic → Redis state: uses · Stores session and rate-limit related chat state.
- Checkout logic → Redis state: persists · Stores checkout progress and cart-linked order state.
- Kapruka MCP → Kapruka MCP: bridges to · Wraps the external commerce service boundary.
- Neo4j graph → Neo4j DB: stores/queries · Reads and writes ontology and recommendation data.
- Redis state → Redis: backed by · Operational state is persisted in Redis.
- Zep memory → Zep: backed by · Long-term memory is stored in Zep.
- Gemini AI → Vertex AI: uses · Calls Vertex AI for language and embedding work.
- Analytics → Neo4j DB: writes · Persists co-purchase communities as graph relationships.
- Chat views → Chat route: rendered by · Chat route serves these server-rendered fragments.
- Checkout views → Checkout route: rendered by · Checkout route serves step templates and partials.
- UI parts → Cart route: shared with · Reusable UI parts support cart and product surfaces.
- Client scripts → Chat views: enhances · Client scripts power incremental interactions and SSE.
- Client scripts → Checkout views: enhances · Client scripts support form interactions and countdowns.
