# 3hal0n/kapruka-chatbot architecture

> Architecture diagram of the GitHub repository 3hal0n/kapruka-chatbot, 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/3hal0n/kapruka-chatbot
- Repository: https://github.com/3hal0n/kapruka-chatbot

## Overview

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: [`backend/main.py`](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/main.py) (FastAPI entry), [`backend/agents/router.py`](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/router.py) (Router), [`backend/agents/catalog_agent.py`](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/catalog_agent.py) (Catalog agent), [`frontend/app/page.tsx`](https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/app/page.tsx) (Chat page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_shell["App shell<br/>Next.js app router<br/>[layout.tsx]"]
  node_ui_home["Chat page<br/>landing route<br/>[page.tsx]"]
  node_ui_components["UI blocks<br/>React components"]
  node_ui_state["Gift data<br/>frontend data<br/>[giftProfiles.ts]"]
end

subgraph group_backend["Backend"]
  node_api_entry["FastAPI entry<br/>service entrypoint<br/>[main.py]"]
  node_api_legacy["Alt app<br/>legacy entrypoint<br/>[app.py]"]
  node_route_agent["Router<br/>agent orchestrator<br/>[router.py]"]
  node_catalog_agent["Catalog agent<br/>shopping agent<br/>[catalog_agent.py]"]
  node_logistics_agent["Logistics agent<br/>fulfillment agent<br/>[logistics_agent.py]"]
  node_critic_agent["Critic agent<br/>review agent<br/>[critic_agent.py]"]
  node_st_memory(("Short-term<br/>session memory<br/>[st_memory.py]"))
  node_semantic_memory(("Semantic<br/>structured memory<br/>[semantic_memory.py]"))
  node_lt_memory(("Long-term<br/>vector memory<br/>[lt_memory.py]"))
  node_llm_client["LLM client<br/>model gateway<br/>[client.py]"]
  node_qdrant_store[("Qdrant store<br/>vector db<br/>[qdrant_store.py]")]
  node_profiles_repo[("Profiles repo<br/>profile persistence<br/>[profiles_repo.py]")]
  node_mcp_client["MCP client<br/>integration client<br/>[client.py]"]
  node_ingest_pipeline["Ingest pipeline<br/>catalog pipeline"]
  node_crawl_service["Crawler<br/>data collector<br/>[crawl.py]"]
  node_config_utils["Config & prompts<br/>runtime config<br/>[config.py]"]
end

subgraph group_infra["Infra"]
  node_compose["Compose deploy<br/>deployment<br/>[docker-compose.yml]"]
end

node_ui_home -->|"renders"| node_ui_components
node_ui_shell -->|"hosts"| node_ui_home
node_ui_home -->|"calls API"| node_api_entry
node_ui_state -->|"feeds"| node_ui_home
node_api_entry -->|"dispatches"| node_route_agent
node_route_agent -->|"selects"| node_catalog_agent
node_route_agent -->|"selects"| node_logistics_agent
node_route_agent -->|"selects"| node_critic_agent
node_catalog_agent -->|"uses"| node_llm_client
node_logistics_agent -->|"uses"| node_llm_client
node_critic_agent -->|"uses"| node_llm_client
node_catalog_agent -->|"retrieves"| node_qdrant_store
node_catalog_agent -->|"consults"| node_lt_memory
node_logistics_agent -->|"consults"| node_semantic_memory
node_route_agent -->|"reads/writes"| node_st_memory
node_lt_memory -->|"backs"| node_qdrant_store
node_semantic_memory -->|"persists"| node_profiles_repo
node_api_entry -->|"integrates"| node_mcp_client
node_ingest_pipeline -->|"collects"| node_crawl_service
node_ingest_pipeline -->|"loads"| node_qdrant_store
node_ingest_pipeline -->|"configured by"| node_config_utils
node_api_entry -->|"configured by"| node_config_utils
node_compose -->|"runs"| node_api_entry
node_compose -->|"runs"| node_ui_shell
node_api_legacy -.->|"alternate"| node_api_entry

click node_ui_shell "https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/app/layout.tsx"
click node_ui_home "https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/app/page.tsx"
click node_ui_components "https://github.com/3hal0n/kapruka-chatbot/tree/main/frontend/components"
click node_ui_state "https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/data/giftProfiles.ts"
click node_api_entry "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/main.py"
click node_api_legacy "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/app.py"
click node_route_agent "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/router.py"
click node_catalog_agent "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/catalog_agent.py"
click node_logistics_agent "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/logistics_agent.py"
click node_critic_agent "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/critic_agent.py"
click node_st_memory "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/memory/st_memory.py"
click node_semantic_memory "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/memory/semantic_memory.py"
click node_lt_memory "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/memory/lt_memory.py"
click node_llm_client "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/llm/client.py"
click node_qdrant_store "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/db/qdrant_store.py"
click node_profiles_repo "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/db/profiles_repo.py"
click node_mcp_client "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/mcp/client.py"
click node_ingest_pipeline "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/services/ingest_to_qdrant.py"
click node_crawl_service "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/services/crawl.py"
click node_config_utils "https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/utils/config.py"
click node_compose "https://github.com/3hal0n/kapruka-chatbot/blob/main/deploy/docker-compose.yml"

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_ui_shell,node_ui_home,node_ui_components,node_ui_state toneBlue
class node_api_entry,node_api_legacy,node_route_agent,node_catalog_agent,node_logistics_agent,node_critic_agent,node_st_memory,node_semantic_memory,node_lt_memory,node_llm_client,node_qdrant_store,node_profiles_repo,node_mcp_client,node_ingest_pipeline,node_crawl_service,node_config_utils toneAmber
class node_compose toneMint
```

## Components

### Frontend

Next.js concierge UI and interaction layer

- [App shell](https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/app/layout.tsx): Next.js app router · Top-level browser app, shared layout, and global styling · `frontend/app/layout.tsx`
- [Chat page](https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/app/page.tsx): landing route · Main concierge experience and entry page · `frontend/app/page.tsx`
- [UI blocks](https://github.com/3hal0n/kapruka-chatbot/tree/main/frontend/components): React components · Chat bubbles, cart, cards, sidebar, modal, and mascot components · `frontend/components`
- [Gift data](https://github.com/3hal0n/kapruka-chatbot/blob/main/frontend/data/giftProfiles.ts): frontend data · Client-facing gift profile data used to drive UI context · `frontend/data/giftProfiles.ts`

### Backend

FastAPI orchestration, memory, retrieval, and agents

- [FastAPI entry](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/main.py): service entrypoint · Main backend server that exposes the chat API and streaming responses · `backend/main.py`
- [Alt app](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/app.py): legacy entrypoint · Alternate or older FastAPI application entrypoint · `backend/app.py`
- [Router](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/router.py): agent orchestrator · Chooses which reasoning path or agent should handle a request · `backend/agents/router.py`
- [Catalog agent](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/catalog_agent.py): shopping agent · Product discovery and catalog-focused reasoning · `backend/agents/catalog_agent.py`
- [Logistics agent](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/logistics_agent.py): fulfillment agent · Shipping, delivery, and order-related guidance · `backend/agents/logistics_agent.py`
- [Critic agent](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/agents/critic_agent.py): review agent · Refines or validates agent outputs before response · `backend/agents/critic_agent.py`
- [Short-term](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/memory/st_memory.py): session memory · Ephemeral conversational state for the active session · `backend/memory/st_memory.py`
- [Semantic](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/memory/semantic_memory.py): structured memory · JSON-backed structured context and recipient knowledge · `backend/memory/semantic_memory.py`
- [Long-term](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/memory/lt_memory.py): vector memory · Qdrant-backed retrieval memory for persistent recall · `backend/memory/lt_memory.py`
- [LLM client](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/llm/client.py): model gateway · Abstraction over the OpenRouter LLM endpoint · `backend/infrastructure/llm/client.py`
- [Qdrant store](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/db/qdrant_store.py): vector db · Vector catalog storage and retrieval layer · `backend/infrastructure/db/qdrant_store.py`
- [Profiles repo](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/db/profiles_repo.py): profile persistence · Local profile and record access layer · `backend/infrastructure/db/profiles_repo.py`
- [MCP client](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/infrastructure/mcp/client.py): integration client · External model context protocol integration boundary · `backend/infrastructure/mcp/client.py`
- [Ingest pipeline](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/services/ingest_to_qdrant.py): catalog pipeline · Crawls product data and loads it into the vector store · `backend/services/ingest_to_qdrant.py`
- [Crawler](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/services/crawl.py): data collector · Collects or scrapes catalog source data · `backend/services/crawl.py`
- [Config & prompts](https://github.com/3hal0n/kapruka-chatbot/blob/main/backend/utils/config.py): runtime config · YAML config and prompt utilities that tune backend behavior · `backend/utils/config.py`

### Infra

Container and deployment boundary

- [Compose deploy](https://github.com/3hal0n/kapruka-chatbot/blob/main/deploy/docker-compose.yml): deployment · Container composition for running frontend and backend together · `deploy/docker-compose.yml`

## Connections

- 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
