# sethikamoraes/kapruka-agentchallenge architecture

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

- Interactive diagram: https://gitdiagram.com/sethikamoraes/kapruka-agentchallenge
- Repository: https://github.com/sethikamoraes/kapruka-agentchallenge

## Overview

1. **What this repo is**
   - A Python **MCP (Model Context Protocol) server** that fronts the **Kapruka.com REST API** and exposes Kapruka capabilities as LLM-friendly tools for MCP clients.

2. **Top-level execution path**
   - `cli.py` is the developer entrypoint. It can start the server, run it over **stdio** for inspection/testing, print registered tools, or ping the upstream API.
   - `src/server.py` is the main server bootstrap and likely the place where the MCP app is assembled and tool handlers are registered.

3. **Inbound server interfaces**
   - The server supports at least two transports:
     - **Streamable HTTP** for normal deployment.
     - **stdio** for local MCP Inspector use.
   - `src/well_known.py` and `src/static/index.html` suggest a small public-facing HTTP surface in addition to MCP transport, likely for discovery/landing-page behavior.

4. **Tool layer**
   - `src/tools/` is the main functional boundary. It is organized by domain:
     - `products.py`
     - `orders.py`
     - `categories.py`
     - `delivery.py`
   - Each module likely defines one tool group and translates MCP calls into Kapruka API operations. This is the primary business-logic layer exposed to clients.

5. **External API boundary**
   - `src/api/client.py` is the single outbound integration layer to Kapruka’s REST API.
   - This is where async HTTP behavior, request/response shaping, and error handling are centralized, keeping the tool modules thin and consistent.

6. **Cross-cutting concerns**
   - `src/cache.py` handles caching for repeated API lookups or metadata.
   - `src/order_rate_limit.py` suggests order-related operations have special throttling or abuse protection.
   - `src/middleware.py` is the shared place for request-level concerns that apply across tools and endpoints.

7. **Observability / activity tracking**
   - `src/activity_log.py` indicates the server records tool usage or API activity, likely to support auditing, diagnostics, or operational reporting.
   - `scripts/setup_activity_table.py` implies this logging may depend on a backing datastore/table that must be provisioned separately.

8. **Configuration boundary**
   - `src/config/settings.py` and `.env.example` show the service is environment-driven.
   - Configuration likely includes Kapruka API base URL, API key, server mode, and deployment/runtime settings. This keeps deployment concerns out of tool code.

9. **Deployment shape**
   - `deploy/kapruka-mcp.service`, `deploy/Caddyfile.snippet`, and `deploy/sync-to-prod.sh` indicate a production setup that runs the Python server as a service and places it behind **Caddy** or another reverse proxy.
   - `server.json` likely contains MCP/server metadata used by hosting or registry tooling.

10. **Development and validation tooling**
   - `scripts/` contains operational helpers:
     - API exploration and model listing
     - registry publishing
     - smoke tests
   - `tests/test_client.py` focuses on the outbound API client, which makes sense because the client is the most critical integration boundary.
   - The repo therefore has a clear split between protocol/server concerns, Kapruka API integration, and small operational scripts.

11. **How data flows through the system**
   - Client request enters via MCP transport.
   - Server dispatches to a tool module.
   - Tool module uses the shared API client, cache, and rate-limit/activity subsystems.
   - The API client calls Kapruka’s REST API.
   - Responses are normalized and returned to the MCP caller, with optional logging and caching applied along the way.

12. **Architecture boundaries to show in a diagram**
   - External clients / MCP Inspector
   - MCP server entrypoints and transport layer
   - Tool modules by domain
   - Shared platform services: config, cache, middleware, rate limiting, activity log
   - External Kapruka REST API
   - Deployment/reverse-proxy/runtime packaging around the server

Main entry points: [`src/server.py`](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/server.py) (Server), [`src/api/client.py`](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/api/client.py) (API client), [`src/tools/orders.py`](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/orders.py) (Orders), [`src/tools/products.py`](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/products.py) (Products)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_server["Server<br/>mcp bootstrap<br/>[server.py]"]
  node_well_known["Well-known<br/>http discovery<br/>[well_known.py]"]
  node_index["Landing page<br/>static html<br/>[index.html]"]
end

subgraph group_tools["Tools"]
  node_products["Products<br/>tool module<br/>[products.py]"]
  node_orders["Orders<br/>tool module<br/>[orders.py]"]
  node_categories["Categories<br/>tool module<br/>[categories.py]"]
  node_delivery["Delivery<br/>tool module<br/>[delivery.py]"]
end

subgraph group_shared["Shared"]
  node_client["API client<br/>rest integration<br/>[client.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_cache(("Cache<br/>[cache.py]"))
  node_rate_limit{{"Rate limit<br/>throttle"}}
  node_middleware["Middleware<br/>[middleware.py]"]
  node_activity_log[("Activity log<br/>audit log<br/>[activity_log.py]")]
end

subgraph group_deploy["Deploy"]
  node_service["Systemd unit<br/>deployment"]
  node_caddy["Caddy snippet<br/>reverse proxy<br/>[Caddyfile.snippet]"]
  node_sync["Sync script<br/>ops script<br/>[sync-to-prod.sh]"]
  node_activity_table["Table setup<br/>ops script"]
  node_server_json["Server spec<br/>metadata<br/>[server.json]"]
end

node_kapruka_api[("Kapruka API<br/>external rest api")]

node_cli -->|"starts"| node_server
node_cli -.->|"inspects"| node_well_known
node_server -->|"registers"| node_products
node_server -->|"registers"| node_orders
node_server -->|"registers"| node_categories
node_server -->|"registers"| node_delivery
node_server -->|"serves"| node_well_known
node_server -->|"serves"| node_index
node_products -->|"calls"| node_client
node_orders -->|"calls"| node_client
node_categories -->|"calls"| node_client
node_delivery -->|"calls"| node_client
node_client -->|"requests"| node_kapruka_api
node_products -.->|"uses"| node_cache
node_orders -.->|"uses"| node_rate_limit
node_server -.->|"applies"| node_middleware
node_orders -.->|"records"| node_activity_log
node_settings -.->|"configures"| node_client
node_settings -.->|"configures"| node_server
node_activity_table -.->|"supports"| node_activity_log
node_service -->|"runs"| node_server
node_caddy -->|"proxies"| node_server
node_sync -.->|"deploys"| node_service
node_server_json -.->|"describes"| node_server

click node_cli "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/cli.py"
click node_server "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/server.py"
click node_well_known "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/well_known.py"
click node_index "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/static/index.html"
click node_products "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/products.py"
click node_orders "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/orders.py"
click node_categories "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/categories.py"
click node_delivery "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/delivery.py"
click node_client "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/api/client.py"
click node_settings "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/config/settings.py"
click node_cache "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/cache.py"
click node_rate_limit "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/order_rate_limit.py"
click node_middleware "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/middleware.py"
click node_activity_log "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/activity_log.py"
click node_service "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/deploy/kapruka-mcp.service"
click node_caddy "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/deploy/Caddyfile.snippet"
click node_sync "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/deploy/sync-to-prod.sh"
click node_activity_table "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/scripts/setup_activity_table.py"
click node_server_json "https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/server.json"

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_well_known,node_index toneBlue
class node_products,node_orders,node_categories,node_delivery toneAmber
class node_client,node_settings,node_cache,node_rate_limit,node_middleware,node_activity_log toneMint
class node_service,node_caddy,node_sync,node_activity_table,node_server_json toneRose
class node_kapruka_api toneNeutral
```

## Components

### Runtime

Server entrypoints and public-facing surfaces

- [CLI](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/cli.py): entrypoint · Developer command entrypoint for running, inspecting, and probing the server · `cli.py`
- [Server](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/server.py): mcp bootstrap · Assembles the MCP app and registers tool handlers · `src/server.py`
- [Well-known](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/well_known.py): http discovery · Small public HTTP discovery surface · `src/well_known.py`
- [Landing page](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/static/index.html): static html · Public landing or discovery page for the HTTP surface · `src/static/index.html`

### Tools

Domain tool modules exposed through MCP

- [Products](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/products.py): tool module · Product-related MCP tools · `src/tools/products.py`
- [Orders](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/orders.py): tool module · Order-related MCP tools · `src/tools/orders.py`
- [Categories](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/categories.py): tool module · Category-related MCP tools · `src/tools/categories.py`
- [Delivery](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/tools/delivery.py): tool module · Delivery-related MCP tools · `src/tools/delivery.py`

### Shared

Cross-cutting platform services

- [API client](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/api/client.py): rest integration · Shared outbound client for Kapruka REST calls · `src/api/client.py`
- [Settings](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/config/settings.py): config · Environment-driven configuration · `src/config/settings.py`
- [Cache](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/cache.py): shared cache · Shared caching for repeated lookups and metadata · `src/cache.py`
- [Rate limit](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/order_rate_limit.py): throttle · Order-specific rate limiting and abuse protection · `src/order_rate_limit.py`
- [Middleware](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/middleware.py): request middleware · Cross-cutting request handling for server paths · `src/middleware.py`
- [Activity log](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/src/activity_log.py): audit log · Tool usage and API activity tracking · `src/activity_log.py`

### Deploy

Runtime packaging and production ops

- [Systemd unit](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/deploy/kapruka-mcp.service): deployment · Production service definition for running the server · `deploy/kapruka-mcp.service`
- [Caddy snippet](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/deploy/Caddyfile.snippet): reverse proxy · Proxy configuration for exposing the server · `deploy/Caddyfile.snippet`
- [Sync script](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/deploy/sync-to-prod.sh): ops script · Production deployment synchronization helper · `deploy/sync-to-prod.sh`
- [Table setup](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/scripts/setup_activity_table.py): ops script · Provisioning helper for activity logging storage · `scripts/setup_activity_table.py`
- [Server spec](https://github.com/sethikamoraes/kapruka-agentchallenge/blob/main/server.json): metadata · Server metadata used by hosting or registry tooling · `server.json`

### Other components

- **Kapruka API**: external rest api · Upstream Kapruka REST API

## Connections

- CLI → Server: starts · CLI launches the MCP server
- CLI → Well-known: inspects · CLI can exercise the HTTP surface
- Server → Products: registers · Server wires domain tools into MCP
- Server → Orders: registers · Server wires domain tools into MCP
- Server → Categories: registers · Server wires domain tools into MCP
- Server → Delivery: registers · Server wires domain tools into MCP
- Server → Well-known: serves · Server exposes the discovery endpoint
- Server → Landing page: serves · Server exposes the public landing page
- Products → API client: calls · Tools delegate to the shared API client
- Orders → API client: calls · Tools delegate to the shared API client
- Categories → API client: calls · Tools delegate to the shared API client
- Delivery → API client: calls · Tools delegate to the shared API client
- API client → Kapruka API: requests · Outbound REST calls to Kapruka
- Products → Cache: uses · Product lookups may be cached
- Orders → Rate limit: uses · Order operations are throttled
- Server → Middleware: applies · Shared request middleware wraps the server
- Orders → Activity log: records · Order and tool activity can be logged
- Settings → API client: configures · Configuration feeds the outbound client
- Settings → Server: configures · Configuration feeds server bootstrap
- Table setup → Activity log: supports · Storage setup backs activity logging
- Systemd unit → Server: runs · System service executes the server process
- Caddy snippet → Server: proxies · Reverse proxy fronts the HTTP server
- Sync script → Systemd unit: deploys · Deployment script updates runtime assets
- Server spec → Server: describes · Metadata points at the server package