Onboarding Wizard

frontend/onboarding-ui/src/
  components/
    AnimatedBackground.tsx   # Visual background animations
    OnboardingLayout.tsx     # Layout wrapper for onboarding pages
    StepIndicator.tsx        # Progress indicator showing current step
    TransitionWrapper.tsx    # Page transition animations
    index.ts                 # Barrel exports
  hooks/
    useOnboardingApi.ts      # Backend API integration
    useOnboardingState.ts    # Onboarding progress state management
  pages/
    WelcomePage.tsx           # Step 1: Welcome and introduction
    PersonaSelectionPage.tsx  # Step 2: Choose user persona
    ConnectionSetupPage.tsx   # Step 3: Connect data source
    FirstQueryPage.tsx        # Step 4: Execute first query
    CompletionPage.tsx        # Step 5: Success and next steps
  App.tsx                    # Root application component
  main.tsx                   # Vite entry point
  index.css                  # Onboarding-specific styles

Step 1          Step 2           Step 3            Step 4           Step 5
Welcome    -->  Persona     -->  Connection   -->  First       -->  Completion
Page            Selection        Setup             Query            Page

Greeting,       Choose role      Connect a         Ask a question   Success!
platform        and workflow     data source       in natural       Navigate to
overview        focus                              language         workbench

+-----------------------------------------------------------+
|  What is your primary role?                                |
|                                                            |
|  +-------------------------+  +-------------------------+  |
|  |                         |  |                         |  |
|  |  [Chart icon]           |  |  [Pipeline icon]        |  |
|  |                         |  |                         |  |
|  |  Data Analyst           |  |  Data Engineer           |  |
|  |  Explore data and       |  |  Build and manage        |  |
|  |  build dashboards       |  |  data pipelines          |  |
|  |                         |  |                         |  |
|  +-------------------------+  +-------------------------+  |
|                                                            |
|  +-------------------------+  +-------------------------+  |
|  |                         |  |                         |  |
|  |  [Model icon]           |  |  [Admin icon]           |  |
|  |                         |  |                         |  |
|  |  Data Scientist         |  |  Platform Administrator  |  |
|  |  Build and deploy       |  |  Manage the platform     |  |
|  |  ML models              |  |  and users               |  |
|  |                         |  |                         |  |
|  +-------------------------+  +-------------------------+  |
|                                                            |
|  [Back]                                        [Continue]  |
+-----------------------------------------------------------+

1. Select data source type
   [PostgreSQL] [MySQL] [Snowflake] [BigQuery] [S3] [CSV Upload] ...
        |
        v
2. Enter connection details
   +-----------------------------------+
   | Host:     [db.example.com       ] |
   | Port:     [5432                  ] |
   | Database: [analytics             ] |
   | Username: [matih_reader          ] |
   | Password: [*****************    ] |
   +-----------------------------------+
        |
        v
3. Test connection
   [Testing...] --> [Connection successful! 12 tables found]
        |
        v
4. Select schema and tables
   [x] public.orders        (1.2M rows)
   [x] public.customers     (45K rows)
   [x] public.products      (2.3K rows)
   [ ] public.audit_log     (8.5M rows)
        |
        v
5. Schema mapping preview
   Detected columns, data types, and relationships

+-----------------------------------------------------------+
|  Ask your first question                                   |
|                                                            |
|  Your data has been connected. Try asking a question:      |
|                                                            |
|  Suggested questions:                                      |
|  - "What are my top 10 customers by revenue?"              |
|  - "Show me the order trend over the last 12 months"       |
|  - "Which products have the highest return rate?"          |
|                                                            |
|  +-----------------------------------------------------+  |
|  | What are my top 10 customers by revenue?             |  |
|  +-----------------------------------------------------+  |
|                                                   [Ask]    |
|                                                            |
|  AI Response:                                              |
|  "Here are your top 10 customers by total revenue:"       |
|                                                            |
|  | Rank | Customer      | Revenue     |                   |
|  |------|---------------|-------------|                   |
|  | 1    | Acme Corp     | $1,245,000  |                   |
|  | 2    | Globex Inc    | $892,000    |                   |
|  | ...  | ...           | ...         |                   |
|                                                            |
|  [View SQL] [Create Dashboard] [Ask Follow-up]             |
|                                                            |
+-----------------------------------------------------------+

// frontend/onboarding-ui/src/hooks/useOnboardingState.ts
export function useOnboardingState() {
  const [step, setStep] = useState<number>(1);
  const [persona, setPersona] = useState<Persona | null>(null);
  const [connection, setConnection] = useState<ConnectionConfig | null>(null);
  const [firstQueryResult, setFirstQueryResult] = useState<QueryResult | null>(null);
  const [isComplete, setIsComplete] = useState(false);
 
  const goToNextStep = useCallback(() => setStep((s) => Math.min(s + 1, 5)), []);
  const goToPreviousStep = useCallback(() => setStep((s) => Math.max(s - 1, 1)), []);
  const canProceed = useMemo(() => {
    switch (step) {
      case 1: return true;
      case 2: return persona !== null;
      case 3: return connection !== null;
      case 4: return firstQueryResult !== null;
      case 5: return true;
      default: return false;
    }
  }, [step, persona, connection, firstQueryResult]);
 
  return {
    step, persona, connection, firstQueryResult, isComplete, canProceed,
    setPersona, setConnection, setFirstQueryResult, setIsComplete,
    goToNextStep, goToPreviousStep,
  };
}

// frontend/onboarding-ui/src/hooks/useOnboardingApi.ts
export function useOnboardingApi() {
  // Test data source connection
  const testConnection = useCallback(async (config: ConnectionConfig) => { /* ... */ }, []);
 
  // Discover schema from connected data source
  const discoverSchema = useCallback(async (connectionId: string) => { /* ... */ }, []);
 
  // Execute first query using AI Service
  const executeFirstQuery = useCallback(async (question: string, connectionId: string) => { /* ... */ }, []);
 
  // Mark onboarding as complete
  const completeOnboarding = useCallback(async (persona: Persona) => { /* ... */ }, []);
 
  return { testConnection, discoverSchema, executeFirstQuery, completeOnboarding };
}