Architecting ALwrity SEO analytics and Agent Flow
Updated: Sep 30
Building a seamless onboarding experience for an SEO platform requires a delicate balance between immediate user gratification and heavy background processing. Recently, we conducted a comprehensive usage audit of the ALwrity Onboarding Flow to map exactly how our backend endpoints, UI components, and persistence layers interact.
Whether you are a developer looking at our API architecture or a product manager interested in data flow, here is a deep dive into how ALwrity orchestrates its 4-step onboarding wizard.
The 4-Step Wizard: From Connection to Personalization
The core of our onboarding journey is divided into four distinct UI steps: Connect Platforms, Research, Personalization, and Finish. Here is how data moves through the system during this process:
Step 0: Connect Platforms (WebsiteStep): This step initiates a full crawl and LLM-powered brand/style analysis. It uses a debounced duplication check to save API calls, instantly loading prior analyses if a user returns. Crucially, while on-page SEO audits are run here, they are kept session-only to provide immediate UI feedback without permanently committing to the database. Google Search Console (GSC) and other OAuth connections (Wix, WordPress, Bing) are also established here.
Step 1: Research (Competitor Analysis): Powered by Exa, this step discovers competitors and social handles. It auto-triggers sitemap analysis and competitive benchmarking, persisting results server-side.
Step 2: Personalization: Using the context gathered in Step 0, this stage generates personalized user personas (spanning voice, image, text, and video).
Step 3: Finish: This finalizes user preferences and officially kicks off heavy, asynchronous tasks like the Deep Competitor Analysis.
Throughout these steps, a SIF (txtai/FAISS) index of website and competitor data is continuously managed to power our backend search capabilities.
Deep-Dive: Managing Competitor Intelligence
Competitor research is arguably the most complex workflow in the onboarding process. The useCompetitorResearchWorkflow orchestrates everything from social discovery to sitemap analysis.
We designed the Research Dashboard with three main tabs:
Competitive Intelligence: Showcases discovered competitors, content pillars, and no-AI sitemap benchmarking.
Strategic Opportunities: Surfaces insights derived from sitemap analysis and our SIF indexing panel.
Smart Background Setup: Manages the health and preferences for three massive scheduled tasks—Deep Competitor Analysis, SIF Indexing, and Market Trends.
The UI Philosophy: We intentionally designed the wizard to show immediate results (like discovered competitors, content pillars, and benchmarking) while hiding heavier tasks. Users are shown a status bulb indicating that deep analysis and market trends are running in the background, with full results deferred to their SEO Dashboard.
The Power of Style Detection Downstream
When a user hits "Analyze" in Step 0, they aren't just getting a quick crawl. The /style-detection/complete pipeline generates a comprehensive package: crawl results, SEO audits, sitemap analysis, style patterns, and content strategy guidelines.
This single data record becomes the foundational context for the rest of the platform. It feeds directly into Step 2 for persona generation, instructs the Canonical Profile Builder for content planning, and is indexed into SIF. Even the SEO Dashboard later re-queries this exact analysis to generate strategic "Winning Moves."
Identifying the Gaps: Where Onboarding Misses Existing Tools
An audit isn't useful unless it highlights areas for improvement. We identified several gaps where our existing SEO tools are not yet fully leveraged during onboarding:
Underutilized SEO Tools Panel: We have 8 powerful tools (including meta-descriptions, PageSpeed, and image-alt tools) that currently live exclusively in the dashboard. For instance, the style analysis in Step 0 yields perfect target keywords and voice data that could automatically pre-fill meta-description generation, but this connection isn't wired up yet.
The GSC Disconnect: In Step 0, we require users to connect their Google Search Console via OAuth. However, we don't utilize this integration during onboarding. The advanced GSC trio (strategy-insights, opportunity-ranking, health-metrics) requires this URL context, yet users only see a "connected" badge instead of an immediate keyword opportunity snapshot.
Persona Generation Silos: While the Personalization Step uses style data, it largely ignores the competitor data and SEO audit readability signals we've already collected.
Redundant Benchmarking: The onboarding flow currently runs its own competitive sitemap benchmarking pipeline rather than utilizing our existing Batch Analyzer tool, duplicating underlying logic.
Surfaced vs. Hidden Data: The Balancing Act
Ultimately, ALwrity's onboarding architecture is a lesson in state management and user psychology.
We surface brand analysis, SEO scores, competitor grids, content pillars, and immediate strategic opportunities. We intentionally hide the heavy lifting—competitive sitemap benchmarking histories, deep competitor analysis reports, and GSC health metrics—reserving them for the comprehensive SEO Dashboard.
By mapping these endpoints and understanding these gaps, we are paving the way for our next iteration of the onboarding flow: one that bridges the gap between initial setup and actionable dashboard insights even faster.
Comments