Skip to main content

Onboarding System

Status: ✅ Complete
Last Updated: 2026-01-23

Overview​

The onboarding system guides new users through essential setup without overwhelming them. It's a 7-step wizard that helps users get started with daily usage, configure essential settings, and understand core concepts. The system is designed to be very handholding with clear instructions, helpful examples, and visual guidance.

User Guide​

What is Onboarding?​

Onboarding is a guided setup wizard that appears when you first sign up for ARC // OS. It walks you through:

  • Creating your first perimeter tasks
  • Setting up your profile (height, currency)
  • Configuring privacy settings
  • Adding personal touches (current book, journal reflection)
  • Learning about gamification

The 7 Steps​

  1. Welcome & Daily Overview - Introduction to ARC and the daily planner
  2. Perimeter Tasks Setup - Create your first reusable tasks
  3. Profile Setup - Enter height and select currency
  4. Privacy Settings - Configure who can see your data
  5. Personal Touch - Add current book (optional) and answer journal questions
  6. Gamification Introduction - Brief overview of XP, battles, and streaks
  7. Completion - Summary and redirect to dashboard

Viewing Your Onboarding Answers​

Your onboarding journal entries are accessible in Settings → Account (Onboarding accordion). You can:

  • View your answers to "Why did you decide to explore ARC today?"
  • View your answers to "What would you like to gain from using ARC?"
  • Edit your answers (they're regular journal entries)
  • See when you completed onboarding

Replaying Onboarding​

You can replay the onboarding wizard anytime from Settings → Account. Click Restart Onboarding.

Note: Replaying onboarding will reset your onboarding completion status, but it won't delete any data you've already created.

Technical Documentation​

Architecture​

The onboarding system consists of:

  • Backend Service (OnboardingService) - Business logic for onboarding flow
  • API Routes (/api/v1/onboarding/*) - REST endpoints for onboarding operations
  • Frontend Component (OnboardingPage) - 7-step wizard UI
  • Route Guard (OnboardingGuard) - Redirects users to onboarding if not complete
  • Hook (useOnboarding) - React hook for onboarding state management

Database Schema​

User Model:

  • onboardingCompleted (Boolean) - Whether user has completed onboarding
  • onboardingCompletedAt (DateTime, nullable) - When onboarding was completed

Journal Questions:

  • Onboarding questions are created as user-specific journal questions
  • Questions are marked as active: false after entries are created
  • Questions are identified by exact text match (hardcoded in service)

Backend Service​

OnboardingService (server/src/services/onboarding.service.ts)

Methods:

  • getOnboardingStatus(userId) - Get onboarding completion status
  • markOnboardingComplete(userId, stepData) - Complete onboarding and process all step data
  • getOnboardingJournalEntries(userId) - Get onboarding journal entries for reflection
  • resetOnboarding(userId) - Reset onboarding status (allow replay)
  • validateOnboardingStep(step, data) - Validate data for each step

Onboarding Step Data:

interface OnboardingStepData {
  tasks?: Array<{ title: string; timebox: number }>;
  height?: number; // in cm
  defaultCurrency?: string;
  privacySettings?: {
    publicIdVisibility?: 'EVERYONE' | 'FRIENDS_ONLY' | 'NONE';
    emailSearchVisibility?: 'EVERYONE' | 'FRIENDS_ONLY' | 'NONE';
    publicProfileVisibility?: 'EVERYONE' | 'FRIENDS_ONLY' | 'NONE';
  };
  currentBook?: {
    title: string;
    author?: string | null;
  } | null;
  journalAnswers?: {
    whyExploreARC: string;
    whatToGain: string;
  };
}

Onboarding Journal Questions:

  • Hardcoded questions (not fetched from API):
    • "Why did you decide to explore ARC today?"
    • "What would you like to gain from using ARC?"
  • Questions are created on-the-fly if they don't exist
  • Questions are marked as active: false after entries are created
  • Questions do NOT appear in regular journal question lists

API Endpoints​

GET /api/v1/onboarding/status

  • Get onboarding completion status
  • Returns: { completed: boolean, completedAt: Date | null }

POST /api/v1/onboarding/complete

  • Mark onboarding as complete
  • Body: OnboardingStepData
  • Creates journal entries, book, updates profile, sets privacy settings, creates tasks
  • Returns: { completed: boolean, completedAt: Date }

GET /api/v1/onboarding/journal-entries

  • Get onboarding journal entries
  • Returns: Array of journal entries for onboarding questions

POST /api/v1/onboarding/reset

  • Reset onboarding status
  • Allows user to replay onboarding wizard

Frontend Implementation​

OnboardingPage (web/src/pages/OnboardingPage.tsx)

Features:

  • 7-step wizard with progress indicator
  • Step-by-step navigation (back/forward)
  • Data persistence (localStorage) - progress saved between sessions
  • Validation for each step
  • Help modals and tooltips for guidance
  • Visual hints and information bubbles

Steps:

  1. Welcome - Introduction and overview
  2. Perimeter Tasks - Create 2-3 tasks (at least 1 required)
  3. Profile Setup - Height (required) and currency (required)
  4. Privacy Settings - Configure visibility (optional, defaults to FRIENDS_ONLY)
  5. Personal Touch - Book (optional) and journal answers (required)
  6. Gamification - Brief introduction
  7. Completion - Summary and redirect

OnboardingGuard (web/src/components/OnboardingGuard.tsx)

  • Redirects users to /onboarding if onboardingCompleted === false
  • Allows access to /onboarding and /login routes
  • Protects all other routes

useOnboarding Hook (web/src/utils/useOnboarding.tsx)

  • Manages onboarding state
  • Provides: status, loading, completeOnboarding(), resetOnboarding()

Integration with Other Services​

Onboarding completion integrates with:

  • DayService - Gets today's day for journal entries
  • JournalService - Creates journal entries and questions
  • BookService - Creates book if provided
  • UserService - Updates profile (height, currency) and privacy settings
  • PerimeterService - Creates perimeter tasks and selects them for today

Data Created During Onboarding:

  • Journal questions (2, marked as inactive)
  • Journal entries (2, linked to today's day)
  • Book (optional, if provided)
  • Perimeter tasks (if provided, automatically selected for today)
  • User profile updates (height, currency)
  • Privacy settings (if provided)

Onboarding Flow Diagram​

┌─────────────────────────────────────────────────────────────────┐
│                    User Signs Up / Logs In                      │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
                    ┌────────────────┐
                    │ Check Onboarding│
                    │    Status      │
                    └────────┬───────┘
                             │
                ┌────────────┴────────────┐
                │                          │
         ┌──────▼──────┐          ┌───────▼──────┐
         │  Completed  │          │ Not Complete │
         └──────┬──────┘          └──────┬───────┘
                │                         │
                │                         ▼
                │              ┌──────────────────┐
                │              │  Onboarding Page  │
                │              │   (7 Steps)     │
                │              └────────┬─────────┘
                │                       │
                │              ┌────────▼─────────┐
                │              │  Step 1: Welcome│
                │              └────────┬─────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Step 2: Perimeter     │
                │              │       Tasks          │
                │              │ (Create 2-3 tasks)    │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Step 3: Profile      │
                │              │ (Height, Currency)   │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Step 4: Privacy      │
                │              │    Settings           │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Step 5: Personal     │
                │              │ (Book, Journal)       │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Step 6: Gamification  │
                │              │    Introduction      │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Step 7: Completion    │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ POST /onboarding/     │
                │              │      complete         │
                │              └────────┬──────────────┘
                │                       │
                │              ┌────────▼──────────────────────────┐
                │              │ Process Step Data:              │
                │              │ - Create journal entries         │
                │              │ - Create book (if provided)      │
                │              │ - Update profile (height, currency)│
                │              │ - Set privacy settings            │
                │              │ - Create perimeter tasks         │
                │              │ - Mark onboarding complete       │
                │              └────────┬──────────────────────────┘
                │                       │
                │              ┌────────▼──────────────┐
                │              │ Redirect to Dashboard│
                │              └────────┬─────────────┘
                │                       │
                └───────────────────────┘
                             │
                             ▼
                    ┌────────────────┐
                    │  Dashboard /   │
                    │  Today Page    │
                    └────────────────┘

Key Points:

  • Users are redirected to onboarding if onboardingCompleted === false
  • Onboarding is a 7-step wizard with progress saved to localStorage
  • All step data is processed when user clicks "Get Started" on step 7
  • After completion, user is redirected to dashboard
  • Onboarding can be replayed from Settings

Design Decisions​

Why 7 Steps?​

The 7-step structure balances:

  • Completeness - Covers essential setup without overwhelming
  • Progressive disclosure - One concept per step
  • Action-oriented - Users complete real tasks, not just tutorials
  • Personal connection - Captures motivation and goals

Why Hardcoded Journal Questions?​

Onboarding questions are hardcoded (not fetched from API) because:

  • Consistency - All users see the same questions
  • Simplicity - No need to manage question templates
  • Special handling - Questions are marked inactive and don't appear in regular journal
  • Reflection - Answers are saved for later reflection

Why Mark Questions as Inactive?​

Onboarding questions are marked as active: false after entries are created because:

  • One-time use - These are onboarding-only questions
  • Clean journal - Don't clutter regular journal question lists
  • Special purpose - They serve a specific onboarding purpose
  • Accessibility - Settings → Account (Onboarding accordion)

Why Not Explain All Features?​

The onboarding wizard intentionally doesn't explain every feature because:

  • Progressive disclosure - Users learn as they need features
  • Avoid overload - Too much information upfront is overwhelming
  • Discovery - Users discover features organically as they use ARC
  • Focus - Emphasize core concepts (perimeter tasks, daily planning, gamification basics)

Why Action-Oriented?​

Users complete real tasks during onboarding (create tasks, set profile, answer questions) because:

  • Immediate value - Users have something set up when they finish
  • Learning by doing - Better understanding through practice
  • Engagement - More engaging than passive tutorials
  • Confidence - Users feel ready to use ARC after completing real tasks

Why Very Handholding?​

The onboarding is designed to be very handholding with:

  • Clear instructions at every step
  • Helpful examples and tooltips
  • Visual guidance and hints
  • Validation messages
  • Progress indicators

This ensures:

  • No confusion - Users know exactly what to do
  • Success - Users complete onboarding successfully
  • Confidence - Users feel comfortable using ARC
  • Reduced support - Fewer questions and confusion

Why Save Progress?​

Onboarding progress is saved to localStorage because:

  • Resume capability - Users can close browser and resume later
  • No data loss - Progress isn't lost if browser crashes
  • User-friendly - Better experience for users

Why Allow Replay?​

Users can replay onboarding because:

  • Learning - Users may want to review concepts
  • New features - Onboarding may be updated with new features
  • Flexibility - Some users prefer to go through it again
  • No harm - Replaying doesn't delete any data

Testing​

Backend Tests​

Service Tests (server/src/services/__tests__/onboarding.service.test.ts)

  • 18 tests covering all service methods
  • Tests for: status, completion, journal entries, reset, validation
  • Tests for integration with other services

Route Tests (server/src/routes/__tests__/onboarding.routes.test.ts)

  • Tests for all API endpoints
  • Tests for authentication and authorization
  • Tests for validation and error handling

Frontend Tests​

Component Tests (web/src/pages/__tests__/OnboardingPage.test.tsx)

  • 34 tests covering all 7 steps
  • Tests for: navigation, validation, data persistence, form submission
  • Tests for help modals, tooltips, and visual guidance

Guard Tests (web/src/components/__tests__/OnboardingGuard.test.tsx)

  • 4 tests covering redirect logic
  • Tests for: protected routes, onboarding route access, login route access

Settings Integration Tests (web/src/pages/__tests__/SettingsPage.test.tsx)

  • 7 tests covering onboarding section in Settings
  • Tests for: displaying entries, editing entries, empty state, restart button

E2E Tests​

E2E Tests (e2e/onboarding.spec.ts)

  • Complete onboarding flow end-to-end (all 7 steps)
  • Verify data is saved correctly (journal entries, book, profile updates)
  • Verify journal entries are created and linked to today's day
  • Verify book is created if provided
  • Verify redirect after completion
  • Verify onboarding journal entries are accessible in settings
  • Verify onboarding guard behavior
  • Verify handholding UI elements work (progress indicator, validation, helpful text)

Future Enhancements​

Potential future improvements:

  • A/B testing - Test different onboarding flows
  • Personalization - Customize onboarding based on user goals
  • Analytics - Track where users drop off
  • Video tutorials - Optional video explanations
  • Skip option - Allow advanced users to skip onboarding
  • Multi-language - Support for multiple languages