Building Block View

Level 1: System Overview

building blocks l1

Component Descriptions

Component Responsibility

CLI Interface

Parse commands, validate arguments, display help with examples, interactive configuration

MCP Server

Expose tools via Model Context Protocol, handle streaming responses, serve rendered diagrams

Agent Core

Orchestrate feedback loop, manage iteration state, enforce limits, generate progress updates

Kroki Manager

Route to appropriate Kroki instance (local/remote), download and start Fat-JAR, health checks

Config Manager

Load configuration from env vars, .env files, and YAML, handle precedence, interactive setup

Level 2: Agent Core Details

building blocks l2

Component Responsibilities

Orchestrator

Main state machine controlling the feedback loop. Decides whether to continue iteration based on validation results and limits.

LLM Client

Wrapper around LiteLLM providing retry logic, error handling, and token counting. Supports both text and vision modes.

Prompt Builder

Constructs prompts with appropriate context:

  • Diagram description from user

  • Relevant examples for the diagram type

  • Previous errors (if iterating)

  • Design feedback (if available)

Syntax Validator

Submits diagram source to Kroki, parses error messages, determines if errors are fixable.

Design Analyzer

Only active if vision-capable LLM configured:

  • Renders diagram to PNG

  • Sends to LLM with design evaluation prompt

  • Parses feedback (layout, clarity, C4 compliance, etc.)

Example Provider

Maintains curated examples for each supported diagram type. Examples loaded on-demand to minimize memory usage.

Iteration Limiter

Enforces two limits:

  • Maximum iterations (default: 5)

  • Maximum time (default: 60 seconds) Prevents infinite loops and excessive API costs.

Output Writer

Handles multiple output scenarios:

  • Write source files (.puml, .mmd, etc.)

  • Write rendered images (PNG, SVG)

  • Optionally serve via HTTP and return URLs (MCP mode)