Alternative text for images is one of those aspects that everyone agrees matters, but it rarely receives the attention it deserves. For sites with hundreds or thousands of images, writing descriptions manually is repetitive and easy to postpone. This need led to the creation of an AI alt text generator for WordPress, a project combining computer vision, a scalable backend, and clean integration with the plugin ecosystem. However, the real value lies not just in generating alt text, but in doing it reliably, securely, and measurably. During development, lessons emerged that go far beyond AI: well-designed telemetry, prevention of duplicate events, tracing actions across multiple systems, and privacy by default. Here we share those insights, from the perspective of Q2BSTUDIO, a company specializing in custom software development and advanced technology solutions.
The plugin relies on an architecture that goes beyond the typical WordPress script. On one side, the PHP admin panel handles the media library, while a Node.js backend hosted on Render processes generation requests. Subscription and usage data reside in Supabase, payments are managed via Stripe, and analytics are collected with PostHog. The flow begins when the user requests alt text generation for one or multiple images; the plugin sends an authenticated request to the backend, which validates available quota, sends the image to an AI vision service, saves the result, and returns the description. This all seems straightforward, but each step introduced challenges that forced a redesign of the approach.
The first major challenge was telemetry. At one point, metrics showed '4 generation starts' and '13 completions', which looked like duplicate events. The real cause was that 'start' measured jobs while 'completion' measured individual images within a batch job. Comparing them directly was like comparing shopping trips with items purchased. The solution was to define clear event semantics: generation_job_started, generation_item_completed, generation_job_completed, and generation_job_failed. Each job gets a unique generation_run_id, and each image a generation_item_id. This allows answering specific questions: how many jobs started, how many images were processed, how many jobs fully succeeded, and how many items failed within a batch. The lesson is that event semantics matter as much as collecting them.
The second challenge was preventing duplicate telemetry. Events can fire multiple times due to repeated clicks, re-renders, retries, or emissions from both frontend and backend simultaneously. To make it retry-safe, stable PostHog $insert_id values were added and ownership of each event was defined: the frontend records user intent (e.g., clicking an update button), the backend records successful Stripe Checkout Session creation, Stripe webhooks determine checkout completion and subscription activation, and the backend records alt text only after it has been persisted. This prevents the same business action from being counted two or three times by different parts of the application.
The third challenge was tracing an action across several systems. A checkout process can pass through WordPress, the backend, Stripe, its webhook, Supabase, and PostHog. Without a shared identifier, debugging that journey is painful. To address this, we introduced correlation_id, checkout_attempt_id, generation_run_id, signup_attempt_id, session_id, and site_install_id. These identifiers allow tracking a single action from the plugin through to external services. When a checkout is abandoned or a login fails, the same correlation_id appears across all systems, instead of having to search by timestamps in disconnected data stores.
The fourth challenge was safe authentication telemetry. A generic 'login_failed' event is not very useful because it doesn't indicate whether the cause was incorrect credentials, a disabled account, rate limiting, a network timeout, an unavailable API, token creation failure, or session storage failure. A controlled internal error taxonomy was implemented, with public messages kept generic to avoid revealing whether an account exists. Internal codes such as invalid_credentials, account_disabled, rate_limited, network_timeout, api_unavailable, token_creation_failed, session_creation_failed, and unknown_auth_error are recorded. Passwords, tokens, and raw responses are stripped before telemetry is sent.
The fifth challenge was privacy by default. Product analytics can quickly become a privacy problem if not handled carefully. The telemetry layer removes fields such as email addresses, license keys, access tokens, API keys, alt text content, image filenames, image URLs, prompts, and raw API responses. PostHog session recording is disabled by default. Analytics should describe what happened without copying the content the user was working with.
If we had to start over, we would define the analytics contract before building dashboards, documenting each event with its exact trigger, whether it is frontend- or backend-owned, whether it fires once per user, session, job, item, or transaction, required properties, deduplication strategy, and schema version. Retrofitting clean telemetry is possible, but it's much more work than designing it properly upfront. We would also add correlation IDs from day one: they are cheap to implement and hugely valuable once an app spans multiple services.
The biggest lesson is that 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, and a migration plan for old telemetry. AI may be the headline feature, but reliability is what turns it into a usable product.
At Q2BSTUDIO, we know that behind any seemingly simple solution lies a complexity of integration, security, and analysis that makes the difference. That's why we offer custom artificial intelligence services, as well as consulting in cybersecurity, cloud AWS/Azure, BI with Power BI, and AI agents. Each project teaches us that technical excellence lies not only in the algorithm but in the orchestration of systems, well-designed telemetry, and the end-user experience. This alt text generator is an example: the most valuable part is not the generation itself, but everything around it that makes it work robustly and reliably.
