How 3hal0n/kapruka-chatbot works
1. This repository is a two-tier gifting concierge system: a Next.js frontend for the chat/shop experience and a FastAPI backend that powers conversation, catalog retrieval, and order-related guidance.
2. The frontend is a client-facing React app built with the Next.js App Router. Its main page lives in frontend/app/page.tsx, with shared layout and global styling in layout.tsx and globals.css. UI is composed from modular components such as the chat bubbles, shopping cart panel, product cards, sidebar, modal flows, and branded mascot/animation elements.
3. The frontend’s role is presentation and interaction. It handles the concierge-style interface, visual state, responsive layout, and real-time conversational UX. The README indicates it connects to the backend through NEXT_PUBLIC_BACKEND_URL, so the browser app is intentionally thin and delegates intelligence to the API layer.
4. The backend is the system’s orchestration core. backend/main.py starts the FastAPI service, and the repo description highlights SSE streaming for live responses. There is also a legacy/alternate backend/app.py, but the main runtime entrypoint is the FastAPI server.
5. The backend is organized around a multi-agent architecture in backend/agents/: a router decides which path to take, catalog_agent handles product discovery, logistics_agent handles fulfillment/shipping-related reasoning, and critic_agent appears to review or refine outputs. This is the main reasoning boundary in the system.
6. Persistent and retrieval-backed memory is split into a few layers under backend/memory/: short-term state, semantic memory, and long-term memory. The README also notes a “3-tier memory” design, with Qdrant used for vector-backed long-term recall and JSON-based semantic storage for structured context.
7. External model and retrieval infrastructure lives under backend/infrastructure/. llm/client.py is the abstraction for the OpenRouter LLM endpoint, while db/qdrant_store.py and related models/repos wrap the Qdrant Cloud catalog store and local profile persistence. mcp/client.py indicates live Model Context Protocol integrations are part of the backend boundary as well.
8. Product data enters the system through an ingestion pipeline in backend/services/. crawl.py appears to scrape or collect catalog data, and ingest_to_qdrant.py pushes that content into Qdrant for retrieval. The CLI pipeline in backend/cli/pipeline.py is the operational entrypoint for refreshing the catalog index.
9. There are two notable data stores: backend/data/recipient_profiles.json for profile-like structured data, and backend/gift_profiles.db for local database persistence. The Qdrant vector store is the main semantic catalog backend, while these local assets support profile and state management.
10. The backend is parameterized by backend/config.yaml and utility helpers in backend/utils/, which suggests model routing, prompts, and runtime behavior are intended to be configurable rather than hard-coded. This helps separate application logic from deployment-specific tuning.
11. The repo includes deploy/docker-compose.yml, plus Dockerfiles in both backend and frontend, so the system is designed to be containerized end-to-end. That makes the architectural boundary between browser, API server, and external services very explicit.
12. backend/notebooks/ contains a stepwise exploration of the architecture: config, memory layers, LLM/Qdrant integration, agent prototypes, ingestion, and end-to-end flow. These notebooks are not production runtime, but they document the evolutionary structure of the backend and are useful for understanding intended data flow.
13. In diagram terms, the core flow is: user interacts with the Next.js UI → frontend sends conversation requests to FastAPI → router selects an agent path → agents consult memory, Qdrant catalog, and LLM/MCP services → backend streams the response back to the UI. Optional ingestion flows run separately from the chat path and update the catalog index in Qdrant.
14. A good architectural boundary to preserve is that the frontend does not own business logic or search logic, and the backend does not own presentation. The backend owns orchestration, retrieval, and model calls; the frontend owns conversational UX, cart-like interaction, and display state.
Main entry points: main.py FastAPI entry · router.py Router · catalog_agent.py Catalog agent · page.tsx Chat page
Components 21
Frontend
Next.js concierge UI and interaction layer
- App shell · Top-level browser app, shared layout, and global styling
frontend/app/layout.tsx - Chat page · Main concierge experience and entry page
frontend/app/page.tsx - UI blocks · Chat bubbles, cart, cards, sidebar, modal, and mascot components
frontend/components - Gift data · Client-facing gift profile data used to drive UI context
frontend/data/giftProfiles.ts
Backend
FastAPI orchestration, memory, retrieval, and agents
- FastAPI entry · Main backend server that exposes the chat API and streaming responses
backend/main.py - Alt app · Alternate or older FastAPI application entrypoint
backend/app.py - Router · Chooses which reasoning path or agent should handle a request
backend/agents/router.py - Catalog agent · Product discovery and catalog-focused reasoning
backend/agents/catalog_agent.py - Logistics agent · Shipping, delivery, and order-related guidance
backend/agents/logistics_agent.py - Critic agent · Refines or validates agent outputs before response
backend/agents/critic_agent.py - Short-term · Ephemeral conversational state for the active session
backend/memory/st_memory.py - Semantic · JSON-backed structured context and recipient knowledge
backend/memory/semantic_memory.py - Long-term · Qdrant-backed retrieval memory for persistent recall
backend/memory/lt_memory.py - LLM client · Abstraction over the OpenRouter LLM endpoint
backend/infrastructure/llm/client.py - Qdrant store · Vector catalog storage and retrieval layer
backend/infrastructure/db/qdrant_store.py - Profiles repo · Local profile and record access layer
backend/infrastructure/db/profiles_repo.py - MCP client · External model context protocol integration boundary
backend/infrastructure/mcp/client.py - Ingest pipeline · Crawls product data and loads it into the vector store
backend/services/ingest_to_qdrant.py - Crawler · Collects or scrapes catalog source data
backend/services/crawl.py - Config & prompts · YAML config and prompt utilities that tune backend behavior
backend/utils/config.py
Infra
Container and deployment boundary
- Compose deploy · Container composition for running frontend and backend together
deploy/docker-compose.yml
Connections 25
- Chat page → UI blocks: renders · Page assembles reusable chat and shopping components
- App shell → Chat page: hosts · App router shell provides the main page and layout
- Chat page → FastAPI entry: calls API · Frontend sends conversation and shopping requests to backend
- Gift data → Chat page: feeds · Client-side gift profile data shapes the experience
- FastAPI entry → Router: dispatches · Incoming chat requests are routed to the correct agent path
- Router → Catalog agent: selects · Routes product discovery questions to catalog reasoning
- Router → Logistics agent: selects · Routes fulfillment and shipping questions to logistics reasoning
- Router → Critic agent: selects · Routes outputs through a critique/refinement step when needed
- Catalog agent → LLM client: uses · Agent calls the language model for reasoning and generation
- Logistics agent → LLM client: uses · Agent calls the language model for guidance and response shaping
- Critic agent → LLM client: uses · Critique and refinement are model-assisted
- Catalog agent → Qdrant store: retrieves · Catalog reasoning consults vector-backed product memory
- Catalog agent → Long-term: consults · Uses long-term recall for prior context and preferences
- Logistics agent → Semantic: consults · Uses structured memory for recipient and order context
- Router → Short-term: reads/writes · Session state tracks the active conversation context
- Long-term → Qdrant store: backs · Long-term memory is implemented on top of Qdrant
- Semantic → Profiles repo: persists · Structured memory is stored via local profile persistence
- FastAPI entry → MCP client: integrates · Backend can reach external MCP tools or contexts
- Ingest pipeline → Crawler: collects · Pipeline starts by gathering source catalog data
- Ingest pipeline → Qdrant store: loads · Ingested catalog content is indexed into Qdrant
- Ingest pipeline → Config & prompts: configured by · Pipeline behavior is tuned through shared configuration
- FastAPI entry → Config & prompts: configured by · Runtime behavior and prompts are driven by config
- Compose deploy → FastAPI entry: runs · Container deployment includes the backend service
- Compose deploy → App shell: runs · Container deployment includes the frontend app
- Alt app → FastAPI entry: alternate · Legacy backend entrypoint sits beside the main server