How I Built an AI Alt Text Generator for WordPress — and What I Learned

Accessibility is one of those areas everyone agrees matters, but it often gets pushed down the development queue. Alt text is a good example.

Adding descriptive alt text to every image improves accessibility, helps screen-reader users understand a page, and can support SEO. But for sites with hundreds or thousands of images, writing it manually is repetitive and easy to neglect.

That problem led me to build an AI alt text generator for WordPress.

The problem

WordPress makes it easy to upload images, but maintaining accurate alt text across a large media library is another story. Site owners usually face one of three situations:

• Images have no alt text
• Existing alt text is vague or duplicated
• There are too many images to review manually

I wanted a tool that could cut that workload while keeping the site owner in control.

What the plugin does

• Generate alt text for individual images
• Process multiple missing-alt images in bulk
• Save generated text directly into WordPress
• Track usage and generation limits
• Let users review results before relying on them

The goal isn't to remove human judgment — it's to make the first draft dramatically faster.

The architecture

The project grew into more than a simple WordPress plugin. The current stack:

• WordPress / PHP — plugin interface and media-library integration
• JavaScript — interactive admin workflows
• Node.js — backend API
• Render — backend hosting
• Supabase — account, entitlement, and usage data
• Stripe — subscriptions and checkout
• PostHog — product analytics
• An AI vision service — image analysis and alt-text generation

The WordPress plugin sends an authenticated generation request to the backend. The backend validates the user, checks available quota, processes the image, stores the usage result, and returns the generated description.

For billing, Stripe webhooks are the authoritative source for subscription status. The frontend never assumes a payment succeeded just because the user returned from checkout.

Challenge 1: Job-level vs image-level analytics

One of the most useful lessons came from telemetry. At one point the analytics showed:

• 4 generation starts
• 13 generation completions

That looked like duplicated completion events. The real issue was that the two metrics measured different things: a generation start could represent one bulk job, while completion events represented each image inside that job. Comparing them directly was like comparing shopping trips with items purchased.

I replaced the ambiguous lifecycle with explicit events:

• generation_job_started
• generation_item_completed
• generation_job_completed
• generation_job_failed

Each job now has a generation_run_id, and each image can have its own generation_item_id. That makes it possible to answer useful questions:

• How many jobs started?
• How many images were processed?
• How many jobs fully succeeded?
• How many items failed inside a bulk job?
• How long did each operation take?

Clear event semantics turned out to be as important as collecting the events.

Challenge 2: Preventing duplicate telemetry

Analytics code can fire more often than expected. Events may be duplicated by:

• repeated button clicks
• component re-renders
• retries
• multiple event listeners
• frontend and backend emitting the same event
• repeated webhook delivery

To make events retry-safe, I added stable PostHog $insert_id values and defined which system owns each event:

• The frontend records user intent (e.g. clicking an upgrade button)
• The backend records successful Stripe Checkout Session creation
• Stripe webhooks determine checkout completion and subscription activation
• The backend records alt text only after it has been persisted

This stops the same business action being counted two or three times by different parts of the app.

Challenge 3: Tracing an action across several systems

A single checkout can pass through:

WordPress → Backend API → Render logs → Stripe Checkout → Stripe webhook → Supabase → PostHog

Without a shared identifier, debugging that journey is painful. I introduced:

• correlation_id
• checkout_attempt_id
• generation_run_id
• signup_attempt_id
• session_id
• site_install_id

These let me trace one action from the plugin through the backend and into external services — especially useful when a checkout is abandoned or a login fails. Instead of searching disconnected systems by timestamp, the same correlation value appears throughout the journey.

Challenge 4: Safe authentication telemetry

A generic login_failed event isn't very useful. It doesn't tell you whether the cause was incorrect credentials, a disabled account, rate limiting, a network timeout, an unavailable API, token-creation failure, or session-storage failure.

I added a controlled internal error taxonomy while keeping public error messages generic — that distinction matters because detailed public messages can reveal whether an account exists. The system now records safe internal codes such as:

• invalid_credentials
• account_disabled
• rate_limited
• network_timeout
• api_unavailable
• token_creation_failed
• session_creation_failed
• unknown_auth_error

Passwords, tokens, API keys, and raw server responses are stripped before telemetry is sent.

Challenge 5: Privacy by default

Product analytics can become a privacy problem surprisingly quickly. The telemetry layer now removes fields such as:

• email addresses
• licence keys
• access tokens
• API keys
• alt text content
• image filenames
• image URLs
• prompts
• raw API responses

PostHog session recording is disabled unless explicitly enabled. The analytics should describe what happened without copying the content the user was working with.

What I'd do differently

If I started again, I'd define the analytics contract before building the dashboards, documenting each event with:

• the exact trigger
• whether it's frontend- or backend-owned
• whether it fires once per user, session, job, item, or transaction
• required properties
• deduplication strategy
• schema version

Retrofitting clean telemetry is possible, but it's much more work than designing it properly up front. I'd also add correlation IDs from day one — they're cheap to implement and hugely valuable once an app spans multiple services.

What I learned

The biggest lesson: building the AI generation feature was only one part of the product. A production-ready plugin also needs:

• reliable authentication
• subscription and quota management
• idempotent webhooks
• privacy-safe analytics
• clear event semantics
• error classification
• end-to-end observability
• a migration plan for old telemetry

The AI part may be the headline feature, but reliability is what turns it into a usable product.

What comes next

• releasing the updated plugin telemetry
• deploying the consolidated backend changes
• validating real production events
• running a fully correlated test checkout
• comparing old and new analytics before removing legacy events

I'm also continuing to improve how generated alt text is reviewed and applied within WordPress.

I'd love to hear from other WordPress, accessibility, or SaaS developers: what's been the hardest part of making your plugin production-ready?