AI SEO Audit

1. Overview

SEO audits are time-consuming, repetitive, and inconsistently executed. A good audit touches local presence, on-page structure, schema markup, page speed, and competitive positioning — most of which follows a repeatable pattern. I wanted to test whether AI could handle the analysis layer reliably enough to be useful in a real workflow.

This was my first end-to-end full-stack AI SaaS build. I designed the product architecture, wrote the prompts, and built the entire app myself using Claude Code. The goal wasn't just to ship something — it was to understand what it actually takes to get AI to produce trustworthy, structured output inside a production system.

I designed the audit methodology, locked the technical stack, built the async job pipeline, and acted as the product decision-maker across every tradeoff.

2. Product Question

The core question: Can AI reliably generate structured, actionable SEO audit reports from minimal user inputs — and deliver them in a format a real client could use?

Secondary questions included:

• Where does deterministic code end and AI judgment begin?
• How do you prevent AI from hallucinating findings or skipping critical checks?
• What's the minimum viable workflow for async AI tasks in a production app?
• What quality bar makes this usable for real client projects?

3. Approach

I treated this as a product design problem first, and a coding problem second. Before writing any code, I documented a canonical audit structure based on how I'd run a manual SEO audit — covering GBP competitor analysis, on-page findings, schema markup, and rankability. That document became the source of truth the AI had to match: sections, table formats, and output structure were all locked to it. That single decision turned the product into a system implementing a defined methodology, rather than a flexible AI experiment.

The build used a job queue architecture (pg-boss) to run audits asynchronously: the user submits inputs through a minimal wizard, a worker process picks up the job, runs each audit section independently, and delivers the report via email and in-app viewer. Each section uses deterministic code for data extraction and OpenAI for qualitative analysis — keeping factual grounding in code while using the model only where judgment and synthesis add value.

4. What I Built

5. Key Decisions & Tradeoffs

6. What I Learned

The hardest part wasn't the AI — it was the plumbing. Getting async jobs to run reliably, handle partial failures gracefully, and surface useful errors took more iteration than any prompt work.

Prompt engineering for structured output is a different discipline than conversational prompting. When the AI needs to produce parseable JSON that maps to a specific schema, every ambiguity in the prompt shows up as a broken report. Precision matters more than creativity.

The canonical PDF decision was more important than it seemed at the time. By anchoring the product to a fixed methodology upfront, I avoided a class of problems that come from letting AI outputs drift across runs. That reframing — "this implements a defined audit methodology" rather than "this generates SEO recommendations" — shaped every downstream decision.

This project also clarified what "AI-native" means in practice: not replacing the audit entirely, but compressing hours of manual work into minutes while keeping a human in the loop for final review and delivery.

7. Outcome & Next Steps

The core pipeline architecture works end-to-end: inputs → async job → multi-section AI analysis → HTML report → PDF → email delivery. The architecture is production-capable, though two known issues remain in the backlog: the rankability section falls back to a generic response when SERP comparison data is unavailable, and the report doesn't always reflect the exact number of competitors selected during setup. Both are documented and scoped — not architectural, just unfinished.

The next phase is on two tracks:

Deepening the audit value: Planned additions include a domain authority and backlink health check (comparing DA scores against competitors via the Moz API), and a local map pack grid search visual — a geo-grid showing how the business ranks across different blocks of their city for the target keyword. That last feature alone is a meaningful pricing differentiator.

Moving toward a real product: The UI needs a full redesign before anything else — the current version was built to validate the pipeline, not to impress a client. Alongside that: custom domain migration to seo-audit.mola.design, Stripe integration for plan-based access, multilingual support (EN/FR/ES), and an interactive fix-tracking checklist inside each report so users can mark action items complete and have a reason to return.

The longer-term question this investigation is building toward: can this be lightweight enough to work as a mobile-first product, where a business owner runs their own audit from their phone before a discovery call?

8. Links & Resources

• Codex Prompt v2.0 (Notion — see parent page)
• Full Implementation Plan (Notion — see parent page)
• GBP Audit Reference Doc (Google Doc)
• Linear Project: AI SEO Audit backlog