DEV Community

Vlad Mihalache
Vlad Mihalache

Posted on

Building AI Explain for 260+ calculators (without going broke)

#ai #wordpress #claude #architecture

Users abandon calculator pages because raw numbers don't tell them what to do.

A debt-to-income ratio of 0.42 means nothing without context. Neither does a body fat percentage of 22%, a TDEE of 2,180 calories, or a sous vide time of 4 hours at 56°C. The user gets the number. Then they wonder "ok, but what now?"

We built AI Explain to fix that. Click a button, get a 100-word breakdown in plain English of what your number means and what to do with it. Available on every tool, in all 7 languages.

The problem: doing this for 260+ tools, with growing volume, on a free tier, without burning thousands in API costs.

This article covers how the system actually works, including the caching layer that kept it economically viable.

Why WordPress (yes, really)

First, the unconventional stack choice. Most devs would default to Next.js for something this app-like. We picked WordPress + custom theme + custom REST endpoints. Here's why, and the honest tradeoffs.

What WordPress gave us for free:

  • Polylang handles 7 languages without rewriting i18n from scratch
  • Custom post types fit "tool" as a first-class object
  • Theme + plugin model maps cleanly to "tool registry"
  • Editing pages with non-tool content (about, blog, legal) is trivial for non-devs
  • Hosting on Hostico is €5/month, no Vercel-level surprises at scale

What it cost us:

  • No streaming server-side rendering (each tool is a JS island)
  • Custom REST endpoints for everything dynamic
  • Polylang quirks with shortcodes
  • Slower DX than Next.js with hot reload

Net assessment: for a content-heavy multilingual site where each tool is mostly a self-contained widget, WordPress was the right call. If Toolita were 5 complex apps instead of 260 small ones, Next.js would have won.

Architecture overview

When a user clicks "Explain my result," this happens:

[Tool page]
    ↓
Calculate locally (JS, instant)
    ↓
User clicks "Explain"
    ↓
Frontend: hash tool_id + bucketed inputs + result
    ↓
Frontend: check local LRU cache (sessionStorage)
    ↓ miss
POST /wp-json/toolita/v1/explain
    ↓
WordPress: check transient cache (24-72hr TTL)
    ↓ miss
Build prompt with tool context + language
    ↓
Anthropic API call (Claude Haiku for free tier)
    ↓
Store in transient
    ↓
Return markdown
    ↓
Frontend renders + optionally streams follow-up
Enter fullscreen mode Exit fullscreen mode

The two-layer cache (browser + server) is what keeps the system economical. More on that in a moment.

The REST endpoint

WordPress makes this part clean. Register a custom REST route, validate inputs, handle the call.

// includes/explain/register.php

add_action('rest_api_init', function () {
    register_rest_route('toolita/v1', '/explain', [
        'methods' => 'POST',
        'callback' => 'toolita_handle_explain',
        'permission_callback' => 'toolita_check_rate_limit',
        'args' => [
            'tool_id' => [
                'required' => true,
                'sanitize_callback' => 'sanitize_text_field',
            ],
            'inputs' => [
                'required' => true,
                'validate_callback' => 'is_array',
            ],
            'result' => [
                'required' => true,
            ],
            'lang' => [
                'default' => 'en',
                'sanitize_callback' => 'sanitize_text_field',
                'validate_callback' => function ($value) {
                    return in_array($value, ['en', 'ro', 'es', 'it', 'pt', 'pl', 'de']);
                },
            ],
        ],
    ]);
});

function toolita_handle_explain(WP_REST_Request $request) {
    $tool_id = $request['tool_id'];
    $inputs  = $request['inputs'];
    $result  = $request['result'];
    $lang    = $request['lang'];

    $tool_context = toolita_get_tool_context($tool_id);
    if (!$tool_context) {
        return new WP_Error('unknown_tool', 'Tool not registered', ['status' => 404]);
    }

    $bucketed_inputs = toolita_bucket_inputs($tool_id, $inputs);
    $cache_key = 'explain_' . md5(
        $tool_id . '_' .
        wp_json_encode($bucketed_inputs) . '_' .
        wp_json_encode($result) . '_' .
        $lang
    );

    $cached = get_transient($cache_key);
    if ($cached !== false) {
        return [
            'explanation' => $cached,
            'cached'      => true,
        ];
    }

    $prompt = toolita_build_prompt($tool_context, $inputs, $result, $lang);

    try {
        $response = toolita_call_anthropic($prompt);
        $explanation = $response['content'][0]['text'];

        $ttl = $tool_context['rate_dependent']
            ? 6 * HOUR_IN_SECONDS
            : 48 * HOUR_IN_SECONDS;

        set_transient($cache_key, $explanation, $ttl);

        return [
            'explanation' => $explanation,
            'cached'      => false,
        ];
    } catch (Exception $e) {
        error_log('Toolita explain failed: ' . $e->getMessage());
        return new WP_Error('explain_failed', 'Could not generate explanation', ['status' => 500]);
    }
}
Enter fullscreen mode Exit fullscreen mode

The caching layer that saved us thousands

First version had no caching. We burned through $400 in the first week of beta. The Mortgage Calculator alone was eating $80/day because every user had similar inputs that produced near-identical explanations.

The insight: most users with similar financial profiles get explanations that should be essentially the same. A 30-year-old paying off $5,234 in credit card debt at 22% APR doesn't need a different explanation than a 30-year-old paying off $5,108 at 21.5%. Both get "this is high-interest debt, prioritize it, here's the math on snowball vs avalanche."

So we bucket the inputs before hashing for the cache key.

// includes/explain/bucketing.php

function toolita_bucket_inputs($tool_id, $inputs) {
    $config = toolita_get_bucketing_config($tool_id);
    if (!$config) {
        return $inputs;
    }

    $bucketed = [];

    foreach ($inputs as $key => $value) {
        if (!isset($config[$key])) {
            $bucketed[$key] = $value;
            continue;
        }

        $rule = $config[$key];

        switch ($rule['type']) {
            case 'numeric_range':
                $bucketed[$key] = floor($value / $rule['bucket_size']) * $rule['bucket_size'];
                break;

            case 'numeric_log':
                if ($value <= 0) {
                    $bucketed[$key] = 0;
                } else {
                    $magnitude = pow(10, floor(log10($value)));
                    $bucketed[$key] = floor($value / $magnitude) * $magnitude;
                }
                break;

            case 'categorical':
                $bucketed[$key] = $value;
                break;

            default:
                $bucketed[$key] = $value;
        }
    }

    return $bucketed;
}
Enter fullscreen mode Exit fullscreen mode

Bucketing config per tool category:

$mortgage_bucketing = [
    'home_price'    => ['type' => 'numeric_log'],        // $5234 → $5000, $52340 → $50000
    'down_payment'  => ['type' => 'numeric_log'],
    'interest_rate' => ['type' => 'numeric_range', 'bucket_size' => 0.25],   // 6.74% → 6.50%
    'term_years'    => ['type' => 'categorical'],         // 15, 20, 30 stay as-is
];

$bmi_bucketing = [
    'weight_kg' => ['type' => 'numeric_range', 'bucket_size' => 2],  // 73 → 72
    'height_cm' => ['type' => 'numeric_range', 'bucket_size' => 2],
    'age'       => ['type' => 'numeric_range', 'bucket_size' => 5],
    'gender'    => ['type' => 'categorical'],
];
Enter fullscreen mode Exit fullscreen mode

After two weeks of running with bucketing, our cache hit rate stabilized at 68%. That cut Anthropic API costs by about 3x.

Multilingual prompts (direct translation is wrong)

We learned this the hard way. A direct translation of an English explanation reads awkward in Romanian. The framing, the call-to-action, the level of formality all shift.

So each tool registers a prompt template per language, not one English template that we translate output from.

// tools/finance/mortgage/prompts.php

return [
    'en' => "You are explaining a mortgage calculation to a first-time homebuyer.\n\n" .
            "Inputs: {INPUTS}\n" .
            "Result: {RESULT}\n\n" .
            "Write a friendly 100-120 word explanation. Include one specific actionable tip. " .
            "Use plain English, no jargon. Amounts in USD.",

    'ro' => "Explici un calcul de ipoteca cuiva care vrea sa cumpere prima locuinta.\n\n" .
            "Date introduse: {INPUTS}\n" .
            "Rezultat: {RESULT}\n\n" .
            "Scrie o explicatie prietenoasa de 100-120 cuvinte. Include un sfat practic concret. " .
            "Limbaj clar, fara jargon. Sumele in RON.",

    'es' => "Explicas el cálculo de una hipoteca a alguien que compra su primera vivienda.\n\n" .
            "Datos introducidos: {INPUTS}\n" .
            "Resultado: {RESULT}\n\n" .
            "Escribe una explicación amigable de 100-120 palabras. Incluye un consejo concreto " .
            "y accionable. Lenguaje sencillo, sin jerga. Importes en EUR.",

    'it' => "Spieghi il calcolo di un mutuo a chi sta comprando la prima casa.\n\n" .
            "Dati inseriti: {INPUTS}\n" .
            "Risultato: {RESULT}\n\n" .
            "Scrivi una spiegazione amichevole di 100-120 parole. Includi un consiglio pratico " .
            "concreto. Linguaggio semplice, senza gergo. Importi in EUR.",

    // ... pt, pl, de follow same pattern
];
Enter fullscreen mode Exit fullscreen mode

For tools that are jurisdiction-specific (salary calculators, tax tools), the prompt also includes the relevant legal references for that country.

Rate limiting (because cheap users will hammer you)

Free tier gets 5 explanations per IP per day. Pretty obvious why.

// includes/explain/rate-limit.php

function toolita_check_rate_limit() {
    if (current_user_can('toolita_pro')) {
        return true;
    }

    $ip = toolita_get_client_ip();
    $key = 'rate_explain_' . md5($ip);
    $count = (int) get_transient($key);

    if ($count >= 5) {
        return new WP_Error('rate_limit', 'Daily limit reached. Upgrade to Pro for unlimited.', [
            'status' => 429,
        ]);
    }

    set_transient($key, $count + 1, DAY_IN_SECONDS);
    return true;
}

function toolita_get_client_ip() {
    $headers = ['HTTP_CF_CONNECTING_IP', 'HTTP_X_FORWARDED_FOR', 'REMOTE_ADDR'];
    foreach ($headers as $header) {
        if (!empty($_SERVER[$header])) {
            $ip = explode(',', $_SERVER[$header])[0];
            return trim($ip);
        }
    }
    return '0.0.0.0';
}
Enter fullscreen mode Exit fullscreen mode

The Cloudflare header check matters because Hostico sits behind Cloudflare, so REMOTE_ADDR would otherwise return the Cloudflare edge IP, not the user.

The frontend side

Vanilla JS, no framework. The tool result page has a button. Click it, fetch the explanation, render markdown.

// assets/js/explain.js

(function () {
    const CACHE_KEY_PREFIX = 'toolita_explain_';
    const LOCAL_TTL = 60 * 60 * 1000; // 1 hour client cache

    function getLocalCache(key) {
        try {
            const stored = sessionStorage.getItem(CACHE_KEY_PREFIX + key);
            if (!stored) return null;

            const { value, expires } = JSON.parse(stored);
            if (Date.now() > expires) {
                sessionStorage.removeItem(CACHE_KEY_PREFIX + key);
                return null;
            }
            return value;
        } catch (e) {
            return null;
        }
    }

    function setLocalCache(key, value) {
        try {
            sessionStorage.setItem(CACHE_KEY_PREFIX + key, JSON.stringify({
                value,
                expires: Date.now() + LOCAL_TTL,
            }));
        } catch (e) {
            // Quota exceeded, ignore
        }
    }

    async function fetchExplanation(toolId, inputs, result, lang) {
        const cacheKey = toolId + ':' + JSON.stringify(inputs) + ':' + JSON.stringify(result) + ':' + lang;

        const cached = getLocalCache(cacheKey);
        if (cached) return { explanation: cached, cached: true };

        const response = await fetch('/wp-json/toolita/v1/explain', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ tool_id: toolId, inputs, result, lang }),
        });

        if (response.status === 429) {
            throw new Error('rate_limit');
        }

        if (!response.ok) {
            throw new Error('explain_failed');
        }

        const data = await response.json();
        setLocalCache(cacheKey, data.explanation);
        return data;
    }

    window.ToolitaExplain = { fetchExplanation };
})();
Enter fullscreen mode Exit fullscreen mode

The local sessionStorage cache catches users clicking "Explain" multiple times in the same session. Saves a server roundtrip and shows results instantly.

What we got wrong

A few honest admissions for anyone building something similar:

  1. No caching in v1. Burned $400 in week one. Could have saved that with one day of upfront design.
  2. Too-aggressive cache TTL in v2. 30-day cache meant mortgage explanations were referencing rates from a quarter ago. Users noticed. We had to invalidate everything and add the rate_dependent flag per tool.
  3. Single English prompt translated at output. Output read like a robot in Romanian and Italian. Native prompts per language fixed it instantly.
  4. No bucketing. Cache hit rate was 12% before bucketing. With bucketing, 68%.
  5. No tracking of model usage per tool. When Claude API costs spiked one week, we couldn't tell which tools were responsible. Added per-tool token logging in v3.

What's next

  • Streaming responses for instant feel (token-by-token rendering)
  • Premium tier with Claude Sonnet for free-tier-quality + extras
  • Per-user explanation history (logged-in users)
  • Embed widget support so partners get explanations in their iframe
  • Structured outputs for tools that benefit from tables or charts in the explanation

Try it

If you're curious how it feels in practice, Toolita has 260+ tools, 7 languages, and the Explain button on every calculator result. Free, no signup.

Disclosure: I'm the maker. Feedback welcome, especially on the cache hit rate math or the prompt architecture if you've built something similar.

Code snippets in this article are simplified from production for readability. The production codebase has additional error handling, logging, A/B testing for prompts, and observability hooks.

If you found this useful, I write occasionally about Toolita architecture, programmatic SEO at scale, and content automation.

Top comments (0)