User Onboarding Flow

A modern, UX-focused multi-step onboarding flow with draft save, conditional logic, and resume later features.

Features

• Multi-Step Wizard: Profile -> Company -> Preferences -> Done
• Draft Save: Automatically saves progress at each step
• Resume Later: Users can close and return to continue where they left off
• Conditional Logic: Skip steps based on user selections (e.g., skip preferences if company has existing tools)
• Beautiful UI: Modern, responsive design with smooth animations
• Validation: Real-time form validation with helpful error messages
• API Documentation: OpenAPI/Swagger documentation included

Tech Stack

Backend

• Django 4.2 - Python web framework
• Django REST Framework - API development
• PostgreSQL - Database
• drf-spectacular - OpenAPI documentation

Frontend

• Next.js 14 - React framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• Framer Motion - Animations
• React Hook Form - Form handling
• Zod - Schema validation

Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Using Docker (Recommended)

1. Clone the repository

   git clone https://github.com/yourusername/user-onboarding-flow.git
   cd user-onboarding-flow

2. Copy environment file

   cp .env.example .env

3. Start the application

   docker compose up --build

4. Access the application

   • Frontend: http://localhost:3001
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/api/docs/

   Note: Default ports are 3001 for frontend, 8000 for API, and 5433 for PostgreSQL. These can be changed in docker-compose.yml if needed.

Manual Installation

Backend Setup

1. Navigate to backend directory

   cd backend

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Set environment variables

   export DATABASE_URL=postgres://user:password@localhost:5432/onboarding
   export SECRET_KEY=your-secret-key
   export DEBUG=True

5. Run migrations

   python manage.py migrate

6. Start the server

   python manage.py runserver

Frontend Setup

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Set environment variables

   export NEXT_PUBLIC_API_URL=http://localhost:8000

4. Start the development server

   npm run dev

API Endpoints

Method	Endpoint	Description
GET	/onboarding/me	Get current onboarding status
POST	/onboarding/step/{step}	Save step data (profile, company, preferences)
POST	/onboarding/complete	Mark onboarding as completed
POST	/onboarding/reset	Reset onboarding and clear all data

Example Request

# Get onboarding status
curl -H "X-User-ID: user123" http://localhost:8000/onboarding/me

# Save profile step
curl -X POST http://localhost:8000/onboarding/step/profile \
  -H "Content-Type: application/json" \
  -H "X-User-ID: user123" \
  -d '{
    "data": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com"
    }
  }'

Data Models

OnboardingSession

- user_id: string (unique)
- current_step: enum (profile, company, preferences, done)
- status: enum (in_progress, completed, abandoned)
- created_at: datetime
- updated_at: datetime

OnboardingData

- user_id: string (unique)
- data: JSONB (step data stored as JSON)
- updated_at: datetime

Conditional Logic

The onboarding flow includes smart conditional logic:

1. Skip Preferences: If a company indicates they have existing tools (has_existing_tools: true), the preferences step is skipped and the user goes directly to completion.

2. Step Validation: Each step validates data before allowing progression.

3. Resume Capability: Users can close the browser and return later - their progress is automatically restored.

Project Structure

user-onboarding-flow/
├── backend/
│   ├── config/              # Django settings
│   ├── onboarding/          # Main app
│   │   ├── models.py        # Data models
│   │   ├── serializers.py   # API serializers
│   │   ├── views.py         # API views
│   │   ├── urls.py          # URL routing
│   │   └── tests.py         # Unit tests
│   ├── Dockerfile
│   ├── manage.py
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/             # Next.js app router
│   │   ├── components/      # React components
│   │   │   └── steps/       # Step components
│   │   ├── hooks/           # Custom hooks
│   │   └── lib/             # Utilities & API
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
├── .env.example
└── README.md

Testing

Backend Tests

cd backend
python manage.py test

Frontend Tests

cd frontend
npm test

Environment Variables

Variable	Description	Default
POSTGRES_DB	Database name	onboarding
POSTGRES_USER	Database user	postgres
POSTGRES_PASSWORD	Database password	postgres
SECRET_KEY	Django secret key	-
DEBUG	Debug mode	True
ALLOWED_HOSTS	Allowed hosts	localhost,127.0.0.1
CORS_ALLOWED_ORIGINS	CORS origins	http://localhost:3000
NEXT_PUBLIC_API_URL	Backend API URL	http://localhost:8000

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built with care for a great user experience