YT Title Doctor

Key Metrics

Overview

YT Title Doctor is an asynchronous backend service that analyzes a YouTube channel's recent uploads and uses Gemini AI to generate improved, SEO-focused video title suggestions. The project focuses on workflow orchestration, pub/sub communication, event-driven architecture, and multi-API coordination rather than the feature itself.

Problem

Optimizing YouTube video titles requires understanding content context, audience engagement, and discoverability. Building such a system also introduces challenges around orchestrating multiple APIs, handling failures, and coordinating asynchronous processing workflows.

Solution

Built an event-driven processing pipeline that accepts channel submissions, resolves channel information, retrieves recent videos, generates optimized titles using Gemini AI, and delivers results through email while maintaining isolated processing stages and centralized failure handling.

Architecture

Event-driven workflow architecture implemented using Motia. Requests enter through a submission endpoint and flow through five independent processing stages connected through pub/sub communication. Each stage performs a single responsibility and emits events that trigger downstream processing, while dedicated error-handling workflows manage failure propagation and user notifications.

Challenges

• Designing event-driven workflows instead of traditional request-response systems.
• Coordinating state across asynchronous processing stages.
• Handling pipeline-wide error propagation.
• Managing structured JSON generation from LLM outputs.
• Resolving YouTube channel identity edge cases.
• Integrating multiple third-party APIs reliably.
• Designing failure recovery strategies for distributed workflows.

Lessons Learned

• Event-driven architecture patterns.
• Pub/sub communication models.
• Workflow orchestration concepts.
• The 202 Accepted asynchronous API pattern.
• Structured AI output generation techniques.
• Multi-API integration strategies.
• Failure-mode-oriented system design.
• Differences between prototype and production-grade systems.

Future Improvements

• Persistent job state storage.
• Retry mechanisms for failed jobs.
• Request timeout handling.
• Authentication and authorization.
• API rate limiting.
• Job status tracking endpoint.
• HTML email templates.
• OpenTelemetry tracing.
• Web dashboard.
• Webhook callback support.
• Multi-key quota balancing.