How the audit works.
This page describes the implementation in this repository. It distinguishes declared capability from evidence that actually ran on a specific audit.
Execution path
Validate and queue
The API accepts a public HTTP or HTTPS URL and a fast or deep depth. It normalizes the URL, checks the 48-hour completed-result cache, applies per-IP limits, writes one audit row, and enqueues the same audit ID and selected depth. Partial and failed runs are not reused as cache hits.
Crawl and guard
The worker renders the submitted page with Playwright while HTTP checks inspect status, robots, sitemap, and related headers. If the response is non-successful or the rendered body is effectively empty, the worker stops before scoring and stores a partial result instead of inventing measurements.
Classify
When enabled, a classifier may identify the brand, industry, audience, and up to three candidate competitors. The result is cached in memory and in audit metadata. Failure is non-fatal: later modules use URL-derived fallbacks and record degraded evidence.
Measure and judge
Thirteen Stage-2 modules and the judge pipeline run concurrently where dependencies permit. Modules range from local HTML and tokenization checks to feature-gated provider and source calls. Each dimension stores its score, issues, metadata, and quality state.
Post-process
Feature-gated processors can add schema diagnostics, citations, hallucination history, loop thresholds, intent weighting, perception, competitive decomposition, counterfactual projections, and AI Overview data. A narrator may turn the structured result into plain-language copy.
Score and store
The scorer aggregates the available weighted dimensions and writes the final status, grade, scores, issue rows, usage metadata, worker stamp, and post-processor output. Only a completed result creates or refreshes the 48-hour URL cache. Partial results remain reportable and immediately retryable; failed results remain explicit.
What “22 dimensions” means
The score contract declares 22 weighted slots: two page/SEO dimensions, five judge dimensions, and fifteen mechanism dimensions. It does not mean that every provider or optional source succeeds on every run. Capability flags, credentials, quotas, audit scale, page accessibility, and prior-history requirements determine what evidence is available. The report must therefore be read together with the quality state and Receipts view.
The AIO decision chain
AI visibility is not six independent points that can always compensate for one another. It is a conditional path. Strong conversion design cannot repair a page that was never retrieved, and retrieval does not guarantee that a response will name the brand or cite its domain. ResourceAI therefore shows the weakest observed stage separately from the composite score.
The first five stages are controlled diagnostics over the sources, prompts, providers, and receipts recorded by one run. They are not Google's private ranking metrics. Real outcome validation should come from the Search Console generative AI performance report, AI-search referral sessions, and downstream conversions. Those integrations are not connected in the current repository, so the report names the gap rather than fabricating outcome data.
The audit also avoids treating llms.txt, tiny content chunks, query-variant page factories, or synthetic mentions as universal AIO levers. Google's current generative AI search guidance explicitly prioritizes crawlable, people-first, non-commodity content and warns against those shortcuts. ResourceAI's chunk analysis is a corpus-comparison diagnostic, not a prescription to split prose into artificial fragments.
Evidence quality
Provider and source behavior
The provider type supports OpenAI, Anthropic, Gemini, Perplexity, and DeepSeek. Different capabilities select different subsets. The source dispatcher tries available public, API, cached, and generated sources in order, subject to source availability, quota, circuit state, and request timeout. The authoritative answer for a completed audit is the stored source/provider receipt—not the list of adapters the code could theoretically call.
Database schema
The Supabase client targets the isolated seo_audit schema. The audits row is the aggregate root; normalized issue and capability rows retain detail that should not be flattened into the report JSON.
Capability storage
Fast and Deep are evidence scopes, not plans
Uses the smallest configured sample. Choose it for an initial baseline or to check a recent page edit.
Attempts larger samples across enabled checks, with more repeated questions and broader provider and page-comparison coverage when those sources are available. Choose it for prioritisation or a report you plan to share.
Both depths use the same scoring rules, report sections, and evidence standards. Deep can take longer and can still be partial when a provider or source is unavailable. A Deep score is not automatically higher; it is based on a broader attempted evidence sample.
Operational guarantees and non-guarantees
- The selected audit depth is preserved from intake through execution.
- A queue failure marks the just-created audit failed instead of leaving it queued forever.
- A crawl that cannot produce usable content stops before measurement.
- Expensive jobs have one automatic attempt; retry is a deliberate user action.
- Runtime varies by run and is recorded after completion.
- This is a single-run page audit; recurring monitoring is not part of the current workflow.