# thejandeera/kapruka-mcp architecture

> Architecture diagram of the GitHub repository thejandeera/kapruka-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thejandeera/kapruka-mcp
- Repository: https://github.com/thejandeera/kapruka-mcp

## Overview

1. **Repository shape**
   - This repo is split into two major runtimes:
     - a **Python MCP server** at the repo root (`src/`, `cli.py`)
     - a **Next.js/TypeScript client app** in `ayubowan/`
   - They are related but distinct: the Python side exposes Kapruka API capabilities as MCP tools, while the Next.js app provides the end-user shopping/chat experience.

2. **Core backend purpose: MCP wrapper around Kapruka REST API**
   - The Python server is the integration boundary to the external **Kapruka.com REST API**.
   - Its job is to translate API operations into **MCP tools** consumable by LLMs and MCP clients.
   - The README makes clear the server supports both **streamable HTTP** and **stdio** transports, so transport is separated from the tool logic.

3. **Backend layering**
   - `src/server.py` is the FastMCP entry point.
   - `src/tools/` contains one module per capability area:
     - `products.py`
     - `categories.py`
     - `orders.py`
     - `delivery.py`
   - `src/api/client.py` is the shared async HTTP client layer and centralizes outbound REST calls plus error handling.
   - `src/config/settings.py` holds environment-driven configuration, keeping API endpoint/key concerns out of business logic.

4. **Backend cross-cutting concerns**
   - `src/cache.py` suggests response or lookup caching to reduce repeated API calls.
   - `src/order_rate_limit.py` indicates order-related protections or throttling around sensitive operations.
   - `src/middleware.py` implies request/response handling at the server boundary, likely for transport concerns or observability.
   - `src/activity_log.py` suggests auditing or event recording for tool usage.
   - `src/well_known.py` likely serves discovery metadata for clients.

5. **Backend developer/runtime interface**
   - `cli.py` is the operator-facing entry point for local development and validation.
   - It supports:
     - running the MCP server
     - stdio mode for inspector/debugging
     - pinging the upstream Kapruka API
     - listing registered tools
   - `tests/test_client.py` covers the API client boundary, which is the most important integration seam.

6. **Frontend application purpose**
   - `ayubowan/` is a separate **Next.js app** that provides a shopping/chat UI.
   - It appears to be an AI-assisted storefront, with the user interacting through a chat interface and product/cart components.
   - The frontend is not just static UI; it includes agent logic and server routes, so it acts as a thin application layer over tool/agent capabilities.

7. **Frontend UI composition**
   - `components/` holds the visible experience:
     - `ChatInterface.tsx` for conversational interaction
     - `ProductCard.tsx` for catalog items
     - `CartDrawer.tsx` for cart state and checkout preview
     - `MessageRenderer.tsx` for rendering assistant/user messages
     - `Navbar.tsx` for top-level navigation
   - `store/useStore.ts` indicates client-side state management, likely for cart/session/UI state shared across components.

8. **Frontend agent/orchestration boundary**
   - `agents/orchestrator.ts`, `agents/shopper.ts`, and `agents/tools.ts` show an internal agent layer inside the Next app.
   - This layer likely turns user chat into structured shopping actions and tool calls.
   - `lib/mcp.ts` is the bridge into the MCP world, so the frontend can talk to the backend server instead of embedding Kapruka API logic directly.
   - This keeps the UI decoupled from the external REST API and centralizes backend tool access.

9. **Frontend server routes**
   - `app/api/chat/route.ts` is the main application-facing backend endpoint for chat-driven interactions.
   - `app/api/proxy-image/route.ts` suggests images are fetched through the app server, likely to work around remote image restrictions or CORS/hotlinking.
   - `app/api/test/route.ts` is a small diagnostic route.
   - `app/page.tsx`, `layout.tsx`, and `globals.css` define the app shell and presentation.

10. **Deployment and packaging boundary**
   - `deploy/` contains operational artifacts for production hosting:
     - `kapruka-mcp.service` for systemd
     - `Caddyfile.snippet` for reverse proxying
     - `sync-to-prod.sh` for deployment sync
   - That points to a self-hosted backend deployment behind a web proxy.
   - `server.json`, `pyproject.toml`, and the two `package.json`/lockfile sets reinforce that the repo intentionally ships two independently deployable stacks.

11. **Data flow at a high level**
   - User interacts with the **Next.js UI**.
   - The UI/chat layer uses the **agent/orchestrator** logic and talks to **MCP tools** through `lib/mcp.ts` and the app API routes.
   - The **Python MCP server** receives tool calls, uses `src/api/client.py` to call the external **Kapruka REST API**, and returns structured results.
   - Some operations may flow back through frontend state management (`useStore`) for cart and display updates.

12. **Architectural boundary summary**
   - The clearest separation is:
     - **presentation + conversational orchestration** in `ayubowan/`
     - **API normalization + tool exposure** in the Python MCP server
     - **external commerce data/source of truth** in Kapruka’s REST API
   - If you are drawing the diagram, the key boundaries are the transport boundary (Next.js routes / MCP transport), the tool boundary (MCP server), and the external service boundary (Kapruka API).

Main entry points: [`src/server.py`](https://github.com/thejandeera/kapruka-mcp/blob/main/src/server.py) (MCP server), [`src/api/client.py`](https://github.com/thejandeera/kapruka-mcp/blob/main/src/api/client.py) (API client), [`ayubowan/agents/orchestrator.ts`](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/orchestrator.ts) (Orchestrator), [`src/tools/orders.py`](https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/orders.py) (Orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python MCP server"]
  node_cli["CLI<br/>operator entrypoint<br/>[cli.py]"]
  node_server["MCP server<br/>tool host<br/>[server.py]"]
  node_middleware["Middleware<br/>cross-cutting<br/>[middleware.py]"]
  node_tools_products["Products<br/>MCP tools<br/>[products.py]"]
  node_tools_categories["Categories<br/>MCP tools<br/>[categories.py]"]
  node_tools_orders["Orders<br/>MCP tools<br/>[orders.py]"]
  node_tools_delivery["Delivery<br/>MCP tools<br/>[delivery.py]"]
  node_client["API client<br/>REST adapter<br/>[client.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_cache["Cache<br/>[cache.py]"]
  node_rate_limit["Rate limit<br/>order guard"]
  node_activity_log["Activity log<br/>audit log<br/>[activity_log.py]"]
  node_well_known["Discovery<br/>metadata<br/>[well_known.py]"]
end

subgraph group_frontend["Next.js app"]
  node_mcp_bridge["MCP bridge<br/>client bridge<br/>[mcp.ts]"]
  node_orchestrator["Orchestrator<br/>agent flow<br/>[orchestrator.ts]"]
  node_shopper["Shopper agent<br/>[shopper.ts]"]
  node_agent_tools["Agent tools<br/>agent adapter<br/>[tools.ts]"]
  node_chat_route["Chat API<br/>server route<br/>[route.ts]"]
  node_proxy_image["Image proxy<br/>server route<br/>[route.ts]"]
  node_chat_ui["Chat UI<br/>[ChatInterface.tsx]"]
  node_catalog_ui["Catalog UI<br/>[ProductCard.tsx]"]
  node_state["Store<br/>client state<br/>[useStore.ts]"]
end

subgraph group_ops["Deployment"]
  node_service["Systemd service<br/>ops"]
  node_proxy["Caddy snippet<br/>ops<br/>[Caddyfile.snippet]"]
end

node_cli -->|"run / inspect"| node_server
node_server -->|"wraps"| node_middleware
node_server -->|"exposes"| node_tools_products
node_server -->|"exposes"| node_tools_categories
node_server -->|"exposes"| node_tools_orders
node_server -->|"exposes"| node_tools_delivery
node_tools_products -->|"calls"| node_client
node_tools_categories -->|"calls"| node_client
node_tools_orders -->|"calls"| node_client
node_tools_delivery -->|"calls"| node_client
node_client -->|"reads"| node_settings
node_client -->|"uses"| node_cache
node_tools_orders -->|"guards"| node_rate_limit
node_server -->|"records"| node_activity_log
node_server -->|"publishes"| node_well_known
node_chat_ui -->|"reads/writes"| node_state
node_chat_ui -->|"drives"| node_orchestrator
node_orchestrator -->|"coordinates"| node_shopper
node_orchestrator -->|"uses"| node_agent_tools
node_agent_tools -->|"invokes"| node_mcp_bridge
node_mcp_bridge -->|"tool calls"| node_server
node_chat_route -->|"serves"| node_orchestrator
node_proxy_image -.->|"supports"| node_catalog_ui
node_service -->|"runs"| node_server
node_proxy -->|"fronts"| node_chat_route

click node_cli "https://github.com/thejandeera/kapruka-mcp/blob/main/cli.py"
click node_server "https://github.com/thejandeera/kapruka-mcp/blob/main/src/server.py"
click node_middleware "https://github.com/thejandeera/kapruka-mcp/blob/main/src/middleware.py"
click node_tools_products "https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/products.py"
click node_tools_categories "https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/categories.py"
click node_tools_orders "https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/orders.py"
click node_tools_delivery "https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/delivery.py"
click node_client "https://github.com/thejandeera/kapruka-mcp/blob/main/src/api/client.py"
click node_settings "https://github.com/thejandeera/kapruka-mcp/blob/main/src/config/settings.py"
click node_cache "https://github.com/thejandeera/kapruka-mcp/blob/main/src/cache.py"
click node_rate_limit "https://github.com/thejandeera/kapruka-mcp/blob/main/src/order_rate_limit.py"
click node_activity_log "https://github.com/thejandeera/kapruka-mcp/blob/main/src/activity_log.py"
click node_well_known "https://github.com/thejandeera/kapruka-mcp/blob/main/src/well_known.py"
click node_mcp_bridge "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/lib/mcp.ts"
click node_orchestrator "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/orchestrator.ts"
click node_shopper "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/shopper.ts"
click node_agent_tools "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/tools.ts"
click node_chat_route "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/app/api/chat/route.ts"
click node_proxy_image "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/app/api/proxy-image/route.ts"
click node_chat_ui "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/components/ChatInterface.tsx"
click node_catalog_ui "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/components/ProductCard.tsx"
click node_state "https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/store/useStore.ts"
click node_service "https://github.com/thejandeera/kapruka-mcp/blob/main/deploy/kapruka-mcp.service"
click node_proxy "https://github.com/thejandeera/kapruka-mcp/blob/main/deploy/Caddyfile.snippet"

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_cli,node_server,node_middleware,node_tools_products,node_tools_categories,node_tools_orders,node_tools_delivery,node_client,node_settings,node_cache,node_rate_limit,node_activity_log,node_well_known toneBlue
class node_mcp_bridge,node_orchestrator,node_shopper,node_agent_tools,node_chat_route,node_proxy_image,node_chat_ui,node_catalog_ui,node_state toneAmber
class node_service,node_proxy toneMint
```

## Components

### Python MCP server

Root-level Python runtime exposing Kapruka capabilities as MCP tools.

- [CLI](https://github.com/thejandeera/kapruka-mcp/blob/main/cli.py): operator entrypoint · Local command-line entrypoint for running, inspecting, and pinging the MCP server. · `cli.py`
- [MCP server](https://github.com/thejandeera/kapruka-mcp/blob/main/src/server.py): tool host · FastMCP entrypoint and transport boundary for exposed tools. · `src/server.py`
- [Middleware](https://github.com/thejandeera/kapruka-mcp/blob/main/src/middleware.py): cross-cutting · Request/response handling around the server boundary. · `src/middleware.py`
- [Products](https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/products.py): MCP tools · Product lookup and catalog tool surface. · `src/tools/products.py`
- [Categories](https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/categories.py): MCP tools · Category browsing and hierarchy tool surface. · `src/tools/categories.py`
- [Orders](https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/orders.py): MCP tools · Order creation and order lifecycle tool surface. · `src/tools/orders.py`
- [Delivery](https://github.com/thejandeera/kapruka-mcp/blob/main/src/tools/delivery.py): MCP tools · Delivery and shipping-related tool surface. · `src/tools/delivery.py`
- [API client](https://github.com/thejandeera/kapruka-mcp/blob/main/src/api/client.py): REST adapter · Shared async HTTP client for Kapruka REST calls and error handling. · `src/api/client.py`
- [Settings](https://github.com/thejandeera/kapruka-mcp/blob/main/src/config/settings.py): config · Environment-driven configuration for API and runtime settings. · `src/config/settings.py`
- [Cache](https://github.com/thejandeera/kapruka-mcp/blob/main/src/cache.py): response cache · Shared caching layer for repeated lookups and responses. · `src/cache.py`
- [Rate limit](https://github.com/thejandeera/kapruka-mcp/blob/main/src/order_rate_limit.py): order guard · Order-specific throttling or protection for sensitive operations. · `src/order_rate_limit.py`
- [Activity log](https://github.com/thejandeera/kapruka-mcp/blob/main/src/activity_log.py): audit log · Audit or event recording for tool usage and server activity. · `src/activity_log.py`
- [Discovery](https://github.com/thejandeera/kapruka-mcp/blob/main/src/well_known.py): metadata · Well-known discovery metadata for MCP clients. · `src/well_known.py`

### Next.js app

Separate TypeScript runtime for chat-driven shopping experience.

- [MCP bridge](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/lib/mcp.ts): client bridge · Frontend-side bridge for talking to MCP tools. · `ayubowan/lib/mcp.ts`
- [Orchestrator](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/orchestrator.ts): agent flow · Main shopping/chat coordination layer inside the Next app. · `ayubowan/agents/orchestrator.ts`
- [Shopper agent](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/shopper.ts): agent · Agent logic for shopping-oriented reasoning and actions. · `ayubowan/agents/shopper.ts`
- [Agent tools](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/agents/tools.ts): agent adapter · Helpers that map user intents to tool invocations. · `ayubowan/agents/tools.ts`
- [Chat API](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/app/api/chat/route.ts): server route · Primary application route for chat-driven interactions. · `ayubowan/app/api/chat/route.ts`
- [Image proxy](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/app/api/proxy-image/route.ts): server route · Server-side image fetch route for remote image handling. · `ayubowan/app/api/proxy-image/route.ts`
- [Chat UI](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/components/ChatInterface.tsx): Conversational interface for the shopping experience. · `ayubowan/components/ChatInterface.tsx`
- [Catalog UI](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/components/ProductCard.tsx): Visible product and cart presentation components. · `ayubowan/components/ProductCard.tsx`
- [Store](https://github.com/thejandeera/kapruka-mcp/blob/main/ayubowan/store/useStore.ts): client state · Shared client-side state for cart, session, and UI updates. · `ayubowan/store/useStore.ts`

### Deployment

Packaging and operational artifacts for self-hosted deployment.

- [Systemd service](https://github.com/thejandeera/kapruka-mcp/blob/main/deploy/kapruka-mcp.service): ops · Production service definition for running the MCP server. · `deploy/kapruka-mcp.service`
- [Caddy snippet](https://github.com/thejandeera/kapruka-mcp/blob/main/deploy/Caddyfile.snippet): ops · Reverse-proxy configuration snippet for deployment. · `deploy/Caddyfile.snippet`

## Connections

- CLI → MCP server: run / inspect · Operator entrypoint launches and probes the server.
- MCP server → Middleware: wraps · Server boundary is mediated by request handling concerns.
- MCP server → Products: exposes · Registers product tools with MCP clients.
- MCP server → Categories: exposes · Registers category tools with MCP clients.
- MCP server → Orders: exposes · Registers order tools with MCP clients.
- MCP server → Delivery: exposes · Registers delivery tools with MCP clients.
- Products → API client: calls · Tool handlers delegate outbound REST work to the shared client.
- Categories → API client: calls · Tool handlers delegate outbound REST work to the shared client.
- Orders → API client: calls · Tool handlers delegate outbound REST work to the shared client.
- Delivery → API client: calls · Tool handlers delegate outbound REST work to the shared client.
- API client → Settings: reads · HTTP client uses configuration for endpoint and credentials.
- API client → Cache: uses · Client benefits from shared caching for repeated requests.
- Orders → Rate limit: guards · Order operations are protected by throttling or rate limits.
- MCP server → Activity log: records · Server activity and tool usage are audited.
- MCP server → Discovery: publishes · Discovery metadata is exposed alongside the server.
- Chat UI → Store: reads/writes · UI components use shared client state for cart and display updates.
- Chat UI → Orchestrator: drives · Chat interface hands user intent to the orchestration layer.
- Orchestrator → Shopper agent: coordinates · Main orchestrator delegates shopping reasoning to agent logic.
- Orchestrator → Agent tools: uses · Orchestrator uses tool adapters for structured actions.
- Agent tools → MCP bridge: invokes · Agent tooling routes through the MCP bridge.
- MCP bridge → MCP server: tool calls · Frontend reaches the Python MCP server through the bridge.
- Chat API → Orchestrator: serves · Application chat endpoint invokes orchestration.
- Image proxy → Catalog UI: supports · Image proxy backs remote asset rendering in the catalog UI.
- Systemd service → MCP server: runs · System service deploys the MCP server in production.
- Caddy snippet → Chat API: fronts · Reverse proxy can front application routes at deployment time.