# it24100500/ai-agent architecture

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

## Overview

1. **Overall shape**
   - This repo is centered on a **Python MCP server** that exposes the **Kapruka.com REST API** as MCP tools for LLM clients and other MCP consumers.
   - The main production boundary is: **MCP client → FastMCP server → internal tool modules → async HTTP client → Kapruka REST API**.

2. **Primary runtime entry points**
   - `cli.py` is the developer-facing entry point for running the server and utility commands.
   - `src/server.py` is the actual server bootstrap for the MCP runtime.
   - The server supports at least two transports: **streamable HTTP** and **stdio** for MCP Inspector / local tooling.

3. **MCP tool layer**
   - `src/tools/` contains the domain-facing tool groups:
     - `products.py`
     - `orders.py`
     - `categories.py`
     - `delivery.py`
   - These modules are the main contract exposed to MCP clients and likely define the tool schemas, input validation, and tool-specific orchestration logic.
   - This is the layer where the API is reshaped from Kapruka’s raw REST semantics into LLM-friendly operations.

4. **API integration layer**
   - `src/api/client.py` is the outbound integration boundary.
   - It wraps the Kapruka REST API with an **async HTTP client** and centralized error handling.
   - The rest of the system should not talk directly to Kapruka; tools go through this client, which keeps external API concerns isolated.

5. **Cross-cutting runtime concerns**
   - `src/middleware.py` likely hosts request/response concerns that apply across the server, such as logging, headers, authentication-related handling, or other request shaping.
   - `src/cache.py` provides caching support to reduce repeated external API calls and stabilize tool performance.
   - `src/order_rate_limit.py` indicates explicit throttling or protection around order-related actions, which is important because those are usually higher-risk or higher-cost operations.

6. **Configuration boundary**
   - `src/config/settings.py` centralizes environment-based configuration.
   - `.env.example` shows the system is configured primarily through environment variables, including Kapruka API URL and API key.
   - This keeps deployment-specific values out of code and makes the server portable across environments.

7. **Operational and observability support**
   - `src/activity_log.py` plus `scripts/setup_activity_table.py` suggest the server records tool or request activity in a persistent table, likely for auditability or usage tracking.
   - That creates a second data path besides the main API proxy path: **server activity → storage/logging backend**.
   - `tests/test_client.py` shows the HTTP client is a key unit boundary worthy of direct test coverage.

8. **Well-known / metadata support**
   - `src/well_known.py` suggests the server exposes protocol or discovery metadata through a well-known endpoint or standardized integration surface.
   - This is relevant for clients that need to discover server capabilities without hardcoding tool details.

9. **Frontend boundary**
   - `frontend/` is a separate **React + TypeScript** application.
   - Based on the repo structure, it is a standalone UI, likely for browsing or demonstrating functionality, and is architecturally separate from the Python MCP runtime.
   - It should be treated as an independent client-side subsystem rather than part of the server execution path.

10. **Static content**
   - `src/static/index.html` and `src/static/` indicate the Python service also serves some static HTML assets, likely for a landing page, docs, or a minimal web surface.
   - This is distinct from the React frontend, which lives in its own package.

11. **Deployment topology**
   - `deploy/` contains production-oriented artifacts: a **systemd service**, a **Caddy config snippet**, and a **sync-to-prod** script.
   - That implies the server is intended to run as a long-lived Linux service, usually behind a reverse proxy.
   - `server.json` likely supports runtime/hosting configuration for the MCP/server environment.

12. **Developer and validation tooling**
   - `scripts/` includes helpers for API exploration, smoke testing, registry publishing, and activity-table setup.
   - `tests/` contains automated tests, while `docs/` holds API notes and handover material.
   - These support the repo’s main purpose: safely adapting an external commerce API into a stable MCP surface.

13. **Key architectural flow to diagram**
   - A good diagram would show:
     - **MCP clients** on the left
     - **FastMCP server / CLI entrypoint** in the center
     - **Tool modules** as the domain adapter layer
     - **Async Kapruka API client** as the outbound integration boundary
     - **Kapruka REST API** on the right
     - Side paths for **config/env**, **cache**, **rate limiting**, and **activity logging**
     - Separate boxes for **frontend**, **deployment**, and **test/tooling** as supporting subsystems

Main entry points: [`src/server.py`](https://github.com/it24100500/ai-agent/blob/main/src/server.py) (MCP server), [`src/api/client.py`](https://github.com/it24100500/ai-agent/blob/main/src/api/client.py) (API client), [`src/tools/orders.py`](https://github.com/it24100500/ai-agent/blob/main/src/tools/orders.py) (Orders), [`src/config/settings.py`](https://github.com/it24100500/ai-agent/blob/main/src/config/settings.py) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["MCP Runtime"]
  node_node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_node_server["MCP server<br/>runtime<br/>[server.py]"]
  node_node_well_known["Discovery<br/>protocol metadata<br/>[well_known.py]"]
  node_node_static["Static site<br/>assets<br/>[index.html]"]
end

subgraph group_grp_tools["Tool Layer"]
  node_node_products["Products<br/>mcp tools<br/>[products.py]"]
  node_node_orders["Orders<br/>mcp tools<br/>[orders.py]"]
  node_node_categories["Categories<br/>mcp tools<br/>[categories.py]"]
  node_node_delivery["Delivery<br/>mcp tools<br/>[delivery.py]"]
end

subgraph group_grp_integration["Kapruka API"]
  node_node_api_client["API client<br/>async http client<br/>[client.py]"]
  node_node_kapruka_api[("Kapruka REST<br/>external api")]
end

subgraph group_grp_support["Support"]
  node_node_settings["Settings<br/>config<br/>[settings.py]"]
  node_node_middleware["Middleware<br/>cross-cutting<br/>[middleware.py]"]
  node_node_cache["Cache<br/>performance<br/>[cache.py]"]
  node_node_rate_limit["Rate limit<br/>protection"]
  node_node_activity_log[("Activity log<br/>audit<br/>[activity_log.py]")]
end

subgraph group_grp_frontend["Frontend"]
  node_node_frontend["React app<br/>client ui<br/>[App.tsx]"]
end

subgraph group_grp_ops["Ops & Delivery"]
  node_node_deploy["Deploy<br/>ops"]
  node_node_scripts["Scripts<br/>tooling<br/>[smoke_test.py]"]
  node_node_tests["Tests<br/>test suite<br/>[test_client.py]"]
end

node_node_cli -->|"starts"| node_node_server
node_node_server -->|"exposes"| node_node_well_known
node_node_server -->|"registers"| node_node_products
node_node_server -->|"registers"| node_node_orders
node_node_server -->|"registers"| node_node_categories
node_node_server -->|"registers"| node_node_delivery
node_node_server -->|"uses"| node_node_middleware
node_node_server -->|"serves"| node_node_static
node_node_products -->|"calls"| node_node_api_client
node_node_orders -->|"calls"| node_node_api_client
node_node_categories -->|"calls"| node_node_api_client
node_node_delivery -->|"calls"| node_node_api_client
node_node_api_client -->|"requests"| node_node_kapruka_api
node_node_settings -.->|"configures"| node_node_server
node_node_settings -.->|"configures"| node_node_api_client
node_node_cache -.->|"wraps"| node_node_api_client
node_node_rate_limit -.->|"guards"| node_node_orders
node_node_activity_log -.->|"records"| node_node_server
node_node_frontend -->|"consumes"| node_node_server
node_node_deploy -.->|"deploys"| node_node_server
node_node_scripts -.->|"exercises"| node_node_api_client
node_node_tests -.->|"tests"| node_node_api_client

click node_node_cli "https://github.com/it24100500/ai-agent/blob/main/cli.py"
click node_node_server "https://github.com/it24100500/ai-agent/blob/main/src/server.py"
click node_node_well_known "https://github.com/it24100500/ai-agent/blob/main/src/well_known.py"
click node_node_products "https://github.com/it24100500/ai-agent/blob/main/src/tools/products.py"
click node_node_orders "https://github.com/it24100500/ai-agent/blob/main/src/tools/orders.py"
click node_node_categories "https://github.com/it24100500/ai-agent/blob/main/src/tools/categories.py"
click node_node_delivery "https://github.com/it24100500/ai-agent/blob/main/src/tools/delivery.py"
click node_node_api_client "https://github.com/it24100500/ai-agent/blob/main/src/api/client.py"
click node_node_settings "https://github.com/it24100500/ai-agent/blob/main/src/config/settings.py"
click node_node_middleware "https://github.com/it24100500/ai-agent/blob/main/src/middleware.py"
click node_node_cache "https://github.com/it24100500/ai-agent/blob/main/src/cache.py"
click node_node_rate_limit "https://github.com/it24100500/ai-agent/blob/main/src/order_rate_limit.py"
click node_node_activity_log "https://github.com/it24100500/ai-agent/blob/main/src/activity_log.py"
click node_node_static "https://github.com/it24100500/ai-agent/blob/main/src/static/index.html"
click node_node_frontend "https://github.com/it24100500/ai-agent/blob/main/frontend/src/App.tsx"
click node_node_deploy "https://github.com/it24100500/ai-agent/blob/main/deploy/kapruka-mcp.service"
click node_node_scripts "https://github.com/it24100500/ai-agent/blob/main/scripts/smoke_test.py"
click node_node_tests "https://github.com/it24100500/ai-agent/blob/main/tests/test_client.py"

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_node_cli,node_node_server,node_node_well_known,node_node_static toneBlue
class node_node_products,node_node_orders,node_node_categories,node_node_delivery toneAmber
class node_node_api_client,node_node_kapruka_api toneMint
class node_node_settings,node_node_middleware,node_node_cache,node_node_rate_limit,node_node_activity_log toneRose
class node_node_frontend toneIndigo
class node_node_deploy,node_node_scripts,node_node_tests toneTeal
```

## Components

### MCP Runtime

Server entrypoints and protocol surface

- [CLI](https://github.com/it24100500/ai-agent/blob/main/cli.py): entrypoint · Developer command entry for running and managing the server · `cli.py`
- [MCP server](https://github.com/it24100500/ai-agent/blob/main/src/server.py): runtime · Bootstraps the FastMCP runtime and transport setup · `src/server.py`
- [Discovery](https://github.com/it24100500/ai-agent/blob/main/src/well_known.py): protocol metadata · Well-known or discovery surface for clients · `src/well_known.py`
- [Static site](https://github.com/it24100500/ai-agent/blob/main/src/static/index.html): assets · Served HTML assets for a minimal web surface · `src/static/index.html`

### Tool Layer

Domain-facing MCP tools

- [Products](https://github.com/it24100500/ai-agent/blob/main/src/tools/products.py): mcp tools · Tool group for product browsing and lookup · `src/tools/products.py`
- [Orders](https://github.com/it24100500/ai-agent/blob/main/src/tools/orders.py): mcp tools · Tool group for order actions and orchestration · `src/tools/orders.py`
- [Categories](https://github.com/it24100500/ai-agent/blob/main/src/tools/categories.py): mcp tools · Tool group for category navigation and lookup · `src/tools/categories.py`
- [Delivery](https://github.com/it24100500/ai-agent/blob/main/src/tools/delivery.py): mcp tools · Tool group for delivery-related operations · `src/tools/delivery.py`

### Kapruka API

Outbound REST integration boundary

- [API client](https://github.com/it24100500/ai-agent/blob/main/src/api/client.py): async http client · Central Kapruka REST API wrapper and error handling boundary · `src/api/client.py`
- **Kapruka REST**: external api · Upstream commerce API consumed by the server

### Support

Cross-cutting runtime and persistence concerns

- [Settings](https://github.com/it24100500/ai-agent/blob/main/src/config/settings.py): config · Environment-based configuration for API and runtime behavior · `src/config/settings.py`
- [Middleware](https://github.com/it24100500/ai-agent/blob/main/src/middleware.py): cross-cutting · Request and response shaping concerns · `src/middleware.py`
- [Cache](https://github.com/it24100500/ai-agent/blob/main/src/cache.py): performance · Caching layer for repeated API access and stability · `src/cache.py`
- [Rate limit](https://github.com/it24100500/ai-agent/blob/main/src/order_rate_limit.py): protection · Throttling and protection around order actions · `src/order_rate_limit.py`
- [Activity log](https://github.com/it24100500/ai-agent/blob/main/src/activity_log.py): audit · Persistent activity tracking for tools or requests · `src/activity_log.py`

### Frontend

Separate React client application

- [React app](https://github.com/it24100500/ai-agent/blob/main/frontend/src/App.tsx): client ui · Standalone React + TypeScript frontend · `frontend/src/App.tsx`

### Ops & Delivery

Deployment and developer tooling

- [Deploy](https://github.com/it24100500/ai-agent/blob/main/deploy/kapruka-mcp.service): ops · Systemd, proxy, and production sync artifacts · `deploy/kapruka-mcp.service`
- [Scripts](https://github.com/it24100500/ai-agent/blob/main/scripts/smoke_test.py): tooling · Exploration, smoke test, registry, and setup helpers · `scripts/smoke_test.py`
- [Tests](https://github.com/it24100500/ai-agent/blob/main/tests/test_client.py): test suite · Automated coverage for the API client boundary · `tests/test_client.py`

## Connections

- CLI → MCP server: starts · CLI launches the MCP server runtime
- MCP server → Discovery: exposes · Server publishes discovery metadata
- MCP server → Products: registers · Server binds product tools into MCP
- MCP server → Orders: registers · Server binds order tools into MCP
- MCP server → Categories: registers · Server binds category tools into MCP
- MCP server → Delivery: registers · Server binds delivery tools into MCP
- MCP server → Middleware: uses · Server applies shared request handling
- MCP server → Static site: serves · Server also serves static HTML assets
- Products → API client: calls · Tools delegate external reads and actions through the client
- Orders → API client: calls · Order operations go through the API client boundary
- Categories → API client: calls · Category lookups use the shared API client
- Delivery → API client: calls · Delivery operations use the shared API client
- API client → Kapruka REST: requests · Outbound REST calls reach the Kapruka API
- Settings → MCP server: configures · Environment settings shape server startup and behavior
- Settings → API client: configures · API base URL and credentials are injected here
- Cache → API client: wraps · Caching reduces repeated outbound calls
- Rate limit → Orders: guards · Order actions are protected by throttling
- Activity log → MCP server: records · Operational activity is recorded from the runtime
- React app → MCP server: consumes · Separate UI can consume the server as a client
- Deploy → MCP server: deploys · Production artifacts run and proxy the server
- Scripts → API client: exercises · Developer scripts probe the API integration boundary
- Tests → API client: tests · Unit tests focus on the HTTP client boundary