orion/app/modules/tenancy/docs/onboarding.md

Store Onboarding System

The store onboarding system is a mandatory 4-step wizard that guides new stores through the initial setup process after signup. Dashboard access is blocked until onboarding is completed.

Overview

The onboarding wizard consists of four sequential steps:

1. Merchant Profile Setup - Basic merchant and contact information
2. Letzshop API Configuration - Connect to Letzshop marketplace
3. Product & Order Import Configuration - Set up CSV feed URLs
4. Order Sync - Import historical orders with progress tracking

User Flow

Signup Complete
      ↓
Redirect to /store/{code}/onboarding
      ↓
Step 1: Merchant Profile
      ↓
Step 2: Letzshop API (with connection test)
      ↓
Step 3: Product Import Config
      ↓
Step 4: Order Sync (with progress bar)
      ↓
Onboarding Complete
      ↓
Redirect to Dashboard

Key Features

Mandatory Completion

• Dashboard and other protected routes redirect to onboarding if not completed
• Admin can skip onboarding for support cases (via admin API)

Step Validation

• Steps must be completed in order (no skipping ahead)
• Each step validates required fields before proceeding

Progress Persistence

• Onboarding progress is saved in the database
• Users can resume from where they left off
• Page reload doesn't lose progress

Connection Testing

• Step 2 includes real-time Letzshop API connection testing
• Shows success/failure status before saving credentials

Historical Import

• Step 4 triggers a background job for order import
• Real-time progress bar with polling (2-second intervals)
• Shows order count as import progresses

Database Model

StoreOnboarding Table

Column	Type	Description
id	Integer	Primary key
store_id	Integer	Foreign key to stores (unique)
status	String(20)	not_started, in_progress, completed, skipped
current_step	String(30)	Current step identifier
step_*_completed	Boolean	Completion flag per step
step_*_completed_at	DateTime	Completion timestamp per step
skipped_by_admin	Boolean	Admin override flag
skipped_reason	Text	Reason for skip (admin)

Onboarding Steps Enum

class OnboardingStep(str, enum.Enum):
    MERCHANT_PROFILE = "merchant_profile"
    LETZSHOP_API = "letzshop_api"
    PRODUCT_IMPORT = "product_import"
    ORDER_SYNC = "order_sync"

API Endpoints

All endpoints are under /api/v1/store/onboarding/:

Method	Endpoint	Description
GET	/status	Get full onboarding status
GET	/step/merchant-profile	Get merchant profile data
POST	/step/merchant-profile	Save merchant profile
POST	/step/letzshop-api/test	Test API connection
POST	/step/letzshop-api	Save API credentials
GET	/step/product-import	Get import config
POST	/step/product-import	Save import config
POST	/step/order-sync/trigger	Start historical import
GET	/step/order-sync/progress/{job_id}	Get import progress
POST	/step/order-sync/complete	Complete onboarding

Integration Points

Signup Flow

When a store is created during signup, an onboarding record is automatically created:

# In platform_signup_service.py
onboarding_service = OnboardingService(db)
onboarding_service.create_onboarding(store.id)

Route Protection

Protected routes check onboarding status and redirect if not completed:

# In store_pages.py
onboarding_service = OnboardingService(db)
if not onboarding_service.is_completed(current_user.token_store_id):
    return RedirectResponse(f"/store/{store_code}/onboarding")

Historical Import

Step 4 uses the existing LetzshopHistoricalImportJob infrastructure:

order_service = LetzshopOrderService(db)
job = order_service.create_historical_import_job(store_id, user_id)

Frontend Implementation

Template

app/templates/store/onboarding.html:

• Standalone page (doesn't use store base template)
• Progress indicator with step circles
• Animated transitions between steps
• Real-time sync progress bar

JavaScript

static/store/js/onboarding.js:

• Alpine.js component
• API calls for each step
• Connection test functionality
• Progress polling for order sync

Admin Skip Capability

For support cases, admins can skip onboarding:

onboarding_service.skip_onboarding(
    store_id=store_id,
    admin_user_id=admin_user_id,
    reason="Manual setup required for migration"
)

This sets skipped_by_admin=True and allows dashboard access without completing all steps.

Files

File	Purpose
models/database/onboarding.py	Database model and enums
models/schema/onboarding.py	Pydantic schemas
app/services/onboarding_service.py	Business logic
app/api/v1/store/onboarding.py	API endpoints
app/routes/store_pages.py	Page routes and redirects
app/templates/store/onboarding.html	Frontend template
static/store/js/onboarding.js	Alpine.js component
alembic/versions/m1b2c3d4e5f6_add_store_onboarding_table.py	Migration

Testing

Run the onboarding tests:

pytest tests/integration/api/v1/store/test_onboarding.py -v

Configuration

No additional configuration is required. The onboarding system uses existing configurations:

• Letzshop API: Uses LetzshopCredentialsService
• Order Import: Uses LetzshopOrderService
• Email: Uses EmailService for welcome email (sent after signup)