Epic: onboarding-route

[pdcolandrea]

Epic: User Onboarding Route

Overview

Implementation of a streamlined single-endpoint onboarding system that collects 18-20 user profile fields through one API call, stores comprehensive style profiles, and generates initial recommendations. Built on existing Hono + Better Auth + Drizzle stack to maximize code reuse and minimize complexity.

Technical Strategy: Leverage existing authentication infrastructure, extend current database schema, and implement rule-based recommendations as foundation for future AI integration.

Architecture Decisions

Single Endpoint Design

• Decision: Use single POST /api/onboarding endpoint vs multi-step process
• Rationale: Reduces network overhead, simplifies client state management, aligns with mobile-first design
• Trade-off: Less granular analytics but better performance and UX

Database Schema Extension

• Decision: Extend existing user tables vs separate profile service
• Rationale: Leverages current Drizzle ORM setup, maintains data consistency with auth system
• Implementation: Add user_profiles table with foreign key to existing users

Recommendation Engine Approach

• Decision: Rule-based scoring algorithm vs third-party service
• Rationale: No external dependencies, full control over logic, cost-effective for MVP
• Future-proof: Designed to integrate with AI models later

Validation Strategy

• Decision: TypeScript + Drizzle schema validation vs external validation library
• Rationale: Reuses existing patterns, maintains consistency with current codebase

Technical Approach

Backend Services

Core API Implementation

• Single Hono route handler for POST /api/onboarding
• Leverages existing Better Auth middleware for user authentication
• Drizzle ORM for type-safe database operations
• Built-in validation using existing schema patterns

Data Layer

// Extend existing database schema
export const userProfiles = pgTable('user_profiles', {
  id: serial('id').primaryKey(),
  userId: text('user_id').references(() => users.id).notNull(),
  // 18-20 onboarding fields with proper types
  ageRange: text('age_range', { enum: ['18-25', '26-35', '36-45', '45+'] }).notNull(),
  location: text('location').notNull(),
  bodyBuild: text('body_build', { enum: ['slim', 'average', 'athletic', 'broad'] }).notNull(),
  // ... additional fields
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull()
});

Recommendation Logic

• Rule-based scoring system using profile data
• Weighted algorithms for style preferences, body type, lifestyle
• Fallback recommendations for incomplete profiles

Infrastructure

Database Migrations

• Single migration extending current schema
• Indexes on frequently queried fields (userId, stylePreferences)
• Constraints ensuring data integrity

Performance Optimizations

• Connection pooling (existing)
• Query optimization with proper indexing
• Response caching for recommendation data

Monitoring & Analytics

• Built-in request logging (existing Hono middleware)
• Custom metrics for onboarding completion rates
• Error tracking and performance monitoring

Implementation Strategy

Phase 1: Core Infrastructure (Week 1-2)

Set up database schema and basic API endpoint

Phase 2: Business Logic (Week 2-3)

Implement validation, recommendation engine, and analytics

Phase 3: Optimization & Testing (Week 3-4)

Performance tuning, comprehensive testing, and documentation

Risk Mitigation

• Database Migration Risk: Use reversible migrations with rollback plan
• Performance Risk: Load testing with 1000 concurrent requests
• Data Quality Risk: Comprehensive validation and sanitization
• Integration Risk: Early integration testing with React Native team

Task Breakdown Preview

High-level task categories for implementation:

• Database Schema & Migration: Create user_profiles table with 18-20 fields, indexes, constraints
• API Endpoint Implementation: Single POST /api/onboarding route with validation and error handling
• Data Models & Types: TypeScript interfaces and Drizzle schema definitions
• Recommendation Engine: Rule-based algorithm for generating initial style recommendations
• Status & Analytics Endpoints: GET endpoints for onboarding status and basic analytics
• Input Validation & Sanitization: Comprehensive field validation and data sanitization
• Performance Optimization: Query optimization, caching, and load testing
• Integration Testing: End-to-end testing with authentication and recommendation flow
• Documentation & API Spec: OpenAPI documentation and implementation guides

Total: 9 focused tasks covering all requirements

Dependencies

External Dependencies

• React Native app team for frontend integration
• Design team for field requirements and validation rules
• Legal approval for data collection compliance

Internal Dependencies

• ✅ Better Auth authentication system (completed)
• Database migration system and procedures
• Existing Hono application structure
• OpenAPI documentation generation setup

Technical Prerequisites

• Database write permissions for migrations
• Environment configuration for new endpoints
• Integration testing environment setup

Success Criteria (Technical)

Performance Benchmarks

• API response time: <800ms for onboarding submission
• Recommendation generation: <2 seconds
• Database query performance: <100ms for profile retrieval
• Concurrent load: Support 1000+ simultaneous onboarding submissions

Quality Gates

• 100% TypeScript coverage with strict mode
• 95%+ test coverage for onboarding logic
• Zero SQL injection vulnerabilities
• GDPR compliance for data handling

Acceptance Criteria

• Single endpoint accepts all 18-20 fields successfully
• Validates required vs optional fields correctly
• Generates meaningful recommendations from profile data
• Integrates seamlessly with existing authentication
• Provides clear error messages for validation failures

Estimated Effort

Overall Timeline: 4-5 weeks (aligned with PRD requirement)

Week 1-2: Foundation

• Database schema design and migration
• Basic API endpoint structure
• Core validation logic

Week 2-3: Implementation

• Complete business logic implementation
• Recommendation engine development
• Integration with existing systems

Week 3-4: Polish & Testing

• Performance optimization
• Comprehensive testing
• Documentation and API specification

Week 4-5: Integration & Refinement

• React Native integration support
• Analytics implementation
• Final performance tuning

Resource Requirements

• 1 Backend Developer (primary)
• 0.5 DevOps Engineer (database migrations, deployment)
• 0.25 QA Engineer (integration testing)

Critical Path Items

1. Database schema approval and migration
2. Recommendation algorithm design and implementation
3. React Native integration testing
4. Performance validation under load

Risk Buffer: 1 week included for unforeseen integration challenges

Stats

Total tasks: 9
Parallel tasks: 6 (can be worked on simultaneously)
Sequential tasks: 3 (have dependencies)
Estimated total effort: 118 hours

[atharvalohote]

please assign me this issue