Dashboard/Crawler-Factory/Decisions/2026-05-03-WizardInWorkspace.md
Crawler-Factory

Decisions/2026-05-03-WizardInWorkspace.md

Decision: Wizard Embedded in Workspace as "Setup" Page

Date: 2026-05-03 (Session 3) Status: Locked

Decision

The 4-step factory setup wizard (Discover → Review → Configure → Done) lives as the "Setup" page inside the WorkspaceShell, not as a full-screen overlay. The outer Algolia chrome (top bar + left nav) remains visible throughout the wizard flow.

Context

Session 3 built FactoryWizard.tsx as position: fixed; inset: 0 — a full-screen takeover that hides the outer Algolia chrome. The user correctly identified this as wrong: "Why is that in a pop-up? It has to be in screens inline."

The first response was to make it full-screen inline (replacing the modal). But after reviewing the real Algolia dashboard flow (Images 3-7 shared in Session 3), the right architecture became clear:

  1. Algolia's "Add new crawler" immediately opens the crawler's workspace
  2. The per-crawler workspace has a left nav with SETUP/STATUS/CONFIGURATION sections
  3. Our Factory wizard should work the same way — "Add new crawler" opens the factory workspace, the Setup page runs the wizard within the workspace content area

The Flow

  1. User clicks "Add new crawler" on the list
  2. A factory entity is created (e.g. algolia_com)
  3. The factory workspace opens immediately (same pattern as Algolia's native flow)
  4. Default active page is "Setup" (first item under SETUP section in left nav)
  5. The Setup page displays the wizard steps: Discover → Review → Configure → Done
  6. The step breadcrumb lives within the content area — NOT in a separate fixed header
  7. The outer Algolia top bar and left nav stay visible throughout
  8. After Done, workspace transitions to Overview

Consequences

  • Wizard feels native to the Algolia dashboard, not like a separate app
  • No chrome context loss during multi-step setup
  • Consistent with how Algolia handles post-creation workspace (drops into workspace immediately)
  • FactoryWizard.tsx needs to drop position: fixed; inset: 0 and render as a normal content area component
  • D18: Factory entity model — sub-crawlers live inside factory, not in main list
  • D20: Factory creation flow (Add → factory entity → workspace opens → Setup page)