# rumeshmohan/kapruka_agent_challenge architecture

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

## Overview

1. **Overall shape**
   - This is a **Python, Streamlit-based conversational agent app** packaged for **Docker** deployment.
   - The repository is organized around a **single user-facing chat interface** that delegates work to a **router + specialist agents** architecture, with shared memory and an LLM/tooling layer underneath.

2. **Entry points and deployment**
   - `app.py` is the declared Streamlit entrypoint in the README metadata.
   - `ui/app.py` appears to hold the main UI implementation, while `main.py` likely provides an alternate startup path or non-UI bootstrap.
   - `Dockerfile` and `.streamlit/config.toml` define the runtime container and Streamlit execution settings.

3. **Presentation layer**
   - The `ui/` package is the front end boundary: it gathers user input, displays agent responses, and likely manages session state for the chat experience.
   - The README describes the product as supporting **localized trilingual voice and dialect queries**, so the UI is the place where language/dialect entry and conversational output are surfaced.

4. **Conversation routing**
   - `agents/router.py` is the central orchestration point.
   - It likely inspects the user’s message, conversation context, and possibly profile state to decide which specialist agent should handle the request.
   - This is the main architectural boundary between “chat UI” and “domain logic.”

5. **Specialist agents**
   - The agent layer is split into domain-focused modules:
     - `catalog_agent.py` for product discovery / item lookup
     - `checkout_agent.py` for purchase or ordering flows
     - `logistics_agent.py` for delivery, shipping, or fulfillment questions
     - `preference_agent.py` for user preference handling / personalization
     - `chitchat_agent.py` for general conversation and fallback social interaction
   - This suggests a **multi-agent decomposition** rather than a single monolithic assistant.

6. **Quality control loop**
   - `agents/reflection_loop.py` is a separate post-processing step.
   - Architecturally, this implies generated answers may be **reviewed, refined, or retried** before being shown to the user.
   - That makes the response pipeline: input → routing → specialist agent → reflection/improvement → final response.

7. **State and memory**
   - `memory/session_buffer.py` holds per-session conversational state.
   - This is the main persistence boundary for short-term context: user history, intermediate decisions, and possibly selected agent state.
   - `data/profiles.json` looks like static profile or seed data used for personalization or testing.

8. **LLM and tool integration**
   - `utils/llm_services.py` centralizes model access, so all agents likely call through a common LLM abstraction instead of talking to providers directly.
   - `utils/mcp_client.py` indicates integration with **MCP (Model Context Protocol)** services, which is the likely bridge to external tools/data sources.
   - In practice, specialist agents probably invoke the LLM layer first, then call MCP-backed tools when domain data is needed.

9. **Configuration boundary**
   - `config/model.yaml` and `config/params.yaml` hold model/runtime settings such as provider choice, inference parameters, or agent behavior tuning.
   - `utils/config.py` likely loads and normalizes these settings for the rest of the application.
   - This keeps prompts, model selection, and runtime parameters outside the agent code.

10. **Repository-level technology signals**
   - `pyproject.toml`, `requirements.txt`, and `uv.lock` show the project is managed as a modern Python application with locked dependencies.
   - `.example` and `.gitignore` imply environment-variable-based configuration for secrets and deployment-specific values.
   - The Streamlit/Hugging Face-style metadata in `README.md` suggests the app is intended to run as a hosted interactive demo or production prototype.

11. **End-to-end data flow**
   - User input enters through the Streamlit UI.
   - The router chooses the best agent using the current session context.
   - The selected agent consults shared memory, LLM services, and, when needed, MCP tools.
   - The reflection loop can refine the draft answer.
   - The final response is returned to the UI and stored back into the session buffer.

12. **Key architectural boundaries to diagram**
   - **UI boundary**: Streamlit frontend vs. backend reasoning
   - **Orchestration boundary**: router vs. specialist agents
   - **State boundary**: short-term session memory vs. stateless processing
   - **Model/tool boundary**: LLM abstraction vs. MCP external services
   - **Configuration boundary**: YAML/config files vs. runtime code

13. **What is most distinctive here**
   - The repository is not a generic chatbot; it is a **domain-routed, multi-agent assistant** with a dedicated reflection step and external tool connectivity.
   - The architecture is designed to support **localized commerce assistance**: product catalog, checkout, logistics, and personalized preference handling all live as separate agents under one conversational surface.

Main entry points: [`agents/router.py`](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/router.py) (Router), [`ui/app.py`](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/ui/app.py) (Chat UI), [`utils/config.py`](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/config.py) (Config Loader), [`utils/llm_services.py`](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/llm_services.py) (LLM Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_py["app.py<br/>entrypoint<br/>[app.py]"]
  node_ui_app_py["Chat UI<br/>streamlit ui<br/>[app.py]"]
  node_main_py["main.py<br/>bootstrap<br/>[main.py]"]
end

subgraph group_orchestration["Agents"]
  node_router_py{{"Router<br/>orchestrator<br/>[router.py]"}}
  node_catalog_agent_py["Catalog<br/>specialist agent<br/>[catalog_agent.py]"]
  node_checkout_agent_py["Checkout<br/>specialist agent<br/>[checkout_agent.py]"]
  node_logistics_agent_py["Logistics<br/>specialist agent<br/>[logistics_agent.py]"]
  node_preference_agent_py["Preferences<br/>specialist agent"]
  node_chitchat_agent_py["Chitchat<br/>fallback agent<br/>[chitchat_agent.py]"]
  node_reflection_loop_py{{"Reflection<br/>response review<br/>[reflection_loop.py]"}}
end

subgraph group_state["State"]
  node_session_buffer_py[("Session Memory<br/>conversation state<br/>[session_buffer.py]")]
  node_profiles_json["Profiles<br/>seed data<br/>[profiles.json]"]
end

subgraph group_integrations["Services"]
  node_llm_services_py{{"LLM Services<br/>model gateway<br/>[llm_services.py]"}}
  node_mcp_client_py{{"MCP Client<br/>tool bridge<br/>[mcp_client.py]"}}
  node_config_py{{"Config Loader<br/>settings<br/>[config.py]"}}
  node_model_yaml["Model Config<br/>yaml settings<br/>[model.yaml]"]
  node_params_yaml["Params Config<br/>yaml settings<br/>[params.yaml]"]
end

subgraph group_deployment["Deploy"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_streamlit_toml["Streamlit Config<br/>runtime config<br/>[config.toml]"]
end

node_app_py -->|"starts"| node_ui_app_py
node_main_py -->|"boots"| node_ui_app_py
node_ui_app_py -->|"send message"| node_router_py
node_router_py -->|"dispatch"| node_catalog_agent_py
node_router_py -->|"dispatch"| node_checkout_agent_py
node_router_py -->|"dispatch"| node_logistics_agent_py
node_router_py -->|"dispatch"| node_preference_agent_py
node_router_py -->|"dispatch"| node_chitchat_agent_py
node_catalog_agent_py -->|"context"| node_session_buffer_py
node_checkout_agent_py -->|"context"| node_session_buffer_py
node_logistics_agent_py -->|"context"| node_session_buffer_py
node_preference_agent_py -->|"context"| node_session_buffer_py
node_chitchat_agent_py -->|"context"| node_session_buffer_py
node_catalog_agent_py -->|"model call"| node_llm_services_py
node_checkout_agent_py -->|"model call"| node_llm_services_py
node_logistics_agent_py -->|"model call"| node_llm_services_py
node_preference_agent_py -->|"model call"| node_llm_services_py
node_chitchat_agent_py -->|"model call"| node_llm_services_py
node_catalog_agent_py -->|"tools"| node_mcp_client_py
node_checkout_agent_py -->|"tools"| node_mcp_client_py
node_logistics_agent_py -->|"tools"| node_mcp_client_py
node_preference_agent_py -->|"tools"| node_mcp_client_py
node_router_py -->|"review"| node_reflection_loop_py
node_reflection_loop_py -->|"final response"| node_ui_app_py
node_ui_app_py -->|"store state"| node_session_buffer_py
node_preference_agent_py -->|"personalize"| node_profiles_json
node_config_py -->|"load"| node_model_yaml
node_config_py -->|"load"| node_params_yaml
node_ui_app_py -->|"settings"| node_config_py
node_router_py -->|"settings"| node_config_py
node_llm_services_py -->|"settings"| node_config_py
node_mcp_client_py -->|"settings"| node_config_py
node_dockerfile -->|"run"| node_app_py
node_streamlit_toml -->|"runtime"| node_ui_app_py

click node_app_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/app.py"
click node_ui_app_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/ui/app.py"
click node_main_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/main.py"
click node_router_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/router.py"
click node_catalog_agent_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/catalog_agent.py"
click node_checkout_agent_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/checkout_agent.py"
click node_logistics_agent_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/logistics_agent.py"
click node_preference_agent_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/preference_agent.py"
click node_chitchat_agent_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/chitchat_agent.py"
click node_reflection_loop_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/reflection_loop.py"
click node_session_buffer_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/memory/session_buffer.py"
click node_profiles_json "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/data/profiles.json"
click node_llm_services_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/llm_services.py"
click node_mcp_client_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/mcp_client.py"
click node_config_py "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/config.py"
click node_model_yaml "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/config/model.yaml"
click node_params_yaml "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/config/params.yaml"
click node_dockerfile "https://github.com/rumeshmohan/kapruka_agent_challenge/tree/main/Dockerfile"
click node_streamlit_toml "https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/.streamlit/config.toml"

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_py,node_ui_app_py,node_main_py toneBlue
class node_router_py,node_catalog_agent_py,node_checkout_agent_py,node_logistics_agent_py,node_preference_agent_py,node_chitchat_agent_py,node_reflection_loop_py toneAmber
class node_session_buffer_py,node_profiles_json toneMint
class node_llm_services_py,node_mcp_client_py,node_config_py,node_model_yaml,node_params_yaml toneRose
class node_dockerfile,node_streamlit_toml toneIndigo
```

## Components

### Presentation

User-facing Streamlit chat interface and startup entrypoints

- [app.py](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/app.py): entrypoint · Declared Streamlit entrypoint · `app.py`
- [Chat UI](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/ui/app.py): streamlit ui · Main conversational interface · `ui/app.py`
- [main.py](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/main.py): bootstrap · Alternate startup path · `main.py`

### Agents

Routing, specialist agents, and response refinement

- [Router](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/router.py): orchestrator · Selects the right specialist agent · `agents/router.py`
- [Catalog](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/catalog_agent.py): specialist agent · Product discovery and item lookup · `agents/catalog_agent.py`
- [Checkout](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/checkout_agent.py): specialist agent · Purchase and ordering flows · `agents/checkout_agent.py`
- [Logistics](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/logistics_agent.py): specialist agent · Shipping and fulfillment support · `agents/logistics_agent.py`
- [Preferences](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/preference_agent.py): specialist agent · Personalization and user preferences · `agents/preference_agent.py`
- [Chitchat](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/chitchat_agent.py): fallback agent · General conversation and fallback · `agents/chitchat_agent.py`
- [Reflection](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/agents/reflection_loop.py): response review · Refines or retries draft answers · `agents/reflection_loop.py`

### State

Session memory and personalization data

- [Session Memory](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/memory/session_buffer.py): conversation state · Per-session chat context and state · `memory/session_buffer.py`
- [Profiles](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/data/profiles.json): seed data · Static profile data for personalization · `data/profiles.json`

### Services

Shared LLM, tool, and config access

- [LLM Services](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/llm_services.py): model gateway · Shared abstraction for model calls · `utils/llm_services.py`
- [MCP Client](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/mcp_client.py): tool bridge · Connects agents to external tools and data · `utils/mcp_client.py`
- [Config Loader](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/utils/config.py): settings · Loads and normalizes runtime settings · `utils/config.py`
- [Model Config](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/config/model.yaml): yaml settings · Model/provider configuration · `config/model.yaml`
- [Params Config](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/config/params.yaml): yaml settings · Inference and agent tuning parameters · `config/params.yaml`

### Deploy

Container and Streamlit runtime setup

- [Dockerfile](https://github.com/rumeshmohan/kapruka_agent_challenge/tree/main/Dockerfile): container build · Container runtime definition · `Dockerfile`
- [Streamlit Config](https://github.com/rumeshmohan/kapruka_agent_challenge/blob/main/.streamlit/config.toml): runtime config · Streamlit execution settings · `.streamlit/config.toml`

## Connections

- app.py → Chat UI: starts · Entry point launches the chat UI
- main.py → Chat UI: boots · Alternate startup path reaches the UI
- Chat UI → Router: send message · User input is routed to a specialist
- Router → Catalog: dispatch · Routes product queries
- Router → Checkout: dispatch · Routes ordering flows
- Router → Logistics: dispatch · Routes delivery questions
- Router → Preferences: dispatch · Routes personalization requests
- Router → Chitchat: dispatch · Routes general conversation
- Catalog → Session Memory: context · Uses conversational state
- Checkout → Session Memory: context · Uses conversational state
- Logistics → Session Memory: context · Uses conversational state
- Preferences → Session Memory: context · Uses conversational state
- Chitchat → Session Memory: context · Uses conversational state
- Catalog → LLM Services: model call · Generates or interprets responses through shared LLM access
- Checkout → LLM Services: model call · Generates or interprets responses through shared LLM access
- Logistics → LLM Services: model call · Generates or interprets responses through shared LLM access
- Preferences → LLM Services: model call · Generates or interprets responses through shared LLM access
- Chitchat → LLM Services: model call · Generates or interprets responses through shared LLM access
- Catalog → MCP Client: tools · Fetches external data when needed
- Checkout → MCP Client: tools · Fetches external data when needed
- Logistics → MCP Client: tools · Fetches external data when needed
- Preferences → MCP Client: tools · Fetches external data when needed
- Router → Reflection: review · Draft responses may be refined before return
- Reflection → Chat UI: final response · Refined answer is returned to the user interface
- Chat UI → Session Memory: store state · Chat turns are persisted in session memory
- Preferences → Profiles: personalize · Uses profile seed data for user-specific behavior
- Config Loader → Model Config: load · Reads model settings
- Config Loader → Params Config: load · Reads runtime parameters
- Chat UI → Config Loader: settings · Uses shared application configuration
- Router → Config Loader: settings · Uses shared application configuration
- LLM Services → Config Loader: settings · Resolves provider and runtime configuration
- MCP Client → Config Loader: settings · Uses connection and runtime configuration
- Dockerfile → app.py: run · Container launches the Streamlit app
- Streamlit Config → Chat UI: runtime · Controls Streamlit behavior
