aethex-forge/docs/issues/P0-ISSUES.md

P0 Priority Issues (Fix ASAP)

These are critical issues that should be addressed immediately.

---

Issue 1: [P0] Fix onboarding progress loss on page refresh

Labels: bug, P0, onboarding, user-experience

Problem

Users lose all onboarding progress when they refresh the page during the multi-step onboarding flow. This leads to high dropout rates and poor user experience.

Current Behavior

• User starts onboarding at /onboarding
• User completes steps 1-4 of 8-step wizard
• User refreshes page (accidentally or intentionally)
• All progress is lost, user starts from step 1 again

Root Cause

Session storage persistence was removed from client/pages/Onboarding.tsx:238-243. Progress is now only stored in memory (React state), which is lost on page refresh.

Expected Behavior

• Progress should be saved to sessionStorage after each step
• On page load, check sessionStorage for existing progress
• If found, restore user to their last completed step
• Clear sessionStorage only after successful onboarding completion

Technical Details

• File: client/pages/Onboarding.tsx
• Lines: 238-243 (where persistence was removed)
• State to persist: currentStep, formData, userType

Implementation Approach

1. Re-enable sessionStorage persistence with key like aethex_onboarding_progress
2. Save state after each step completion
3. On component mount, check for existing progress
4. Restore state if found
5. Add recovery UI: "Continue where you left off?" prompt
6. Clear storage on successful completion

Acceptance Criteria

• Progress persists across page refreshes
• User can resume from last completed step
• Storage is cleared after onboarding completes
• Works across browser tabs (same session)
• Handles edge cases (corrupted data, version changes)

Impact

• High onboarding dropout rate
• Poor first-time user experience
• Lost user data and effort

---

Issue 2: [P0] Complete Stripe payment integration

Labels: bug, P0, payments, backend, stripe

Problem

The payment flow UI exists but Stripe integration may not be fully implemented. Users cannot upgrade to Pro/Council tiers, preventing monetization.

Current Behavior

• Pricing page at /pricing shows subscription tiers
• "Upgrade" buttons exist for Pro ($9/mo) and Council ($29/mo)
• Clicking upgrade attempts to call /api/subscriptions/create-checkout
• Integration status unknown - needs verification

Missing/Incomplete Features

1. Stripe Checkout Session Creation

   • Verify /api/subscriptions/create-checkout endpoint works
   • Ensure proper price IDs are configured
   • Test redirect flow

2. Webhook Handlers

   • checkout.session.completed - Create subscription in DB
   • customer.subscription.updated - Update tier changes
   • customer.subscription.deleted - Handle cancellations
   • invoice.payment_failed - Handle failed payments

3. Billing Portal

   • "Manage Subscription" button should open Stripe portal
   • Verify /api/subscriptions/manage endpoint
   • Test cancellation and plan changes

4. Database Sync

   • Update profiles.tier on successful payment
   • Track subscription status in DB
   • Store Stripe customer ID and subscription ID

Technical Details

• Files:
  • client/pages/Pricing.tsx (UI)
  • server/index.ts or api/subscriptions/* (backend)
  • Stripe webhooks configuration
• Environment Variables Needed:
  • STRIPE_SECRET_KEY
  • STRIPE_PUBLISHABLE_KEY
  • STRIPE_WEBHOOK_SECRET
  • Price IDs for Pro and Council tiers

Implementation Checklist

• Verify Stripe API keys are configured
• Create/verify product and price IDs in Stripe
• Implement create-checkout endpoint
• Implement manage-subscription endpoint
• Set up webhook endpoint
• Add webhook handlers for all events
• Test full checkout flow
• Test subscription management flow
• Test cancellation flow
• Add error handling and retry logic

Testing Scenarios

1. New user upgrades from Free → Pro
2. Pro user upgrades to Council
3. Council user cancels subscription
4. Payment fails, retry logic
5. User changes payment method
6. User views billing history

Acceptance Criteria

• Users can successfully upgrade to Pro tier
• Users can successfully upgrade to Council tier
• Subscription status syncs to database
• Billing portal opens and works correctly
• Webhooks properly handle all events
• Failed payments are handled gracefully
• Users can cancel subscriptions

Impact

• Cannot monetize the platform
• No paid tier access for users
• Revenue loss

---

Issue 3: [P0] Refactor large components (Feed, ProfilePassport, AuthContext)

Labels: tech-debt, P0, refactoring, performance

Problem

Several components exceed 900+ lines, making them difficult to maintain, test, and debug. This increases bug risk and slows development velocity.

Affected Components

1. AuthContext.tsx (1,246 lines)

Location: client/contexts/AuthContext.tsx

Current Responsibilities: (Too many)

• Session management
• OAuth flow handling
• Email resolution logic
• Profile fetching
• Multiple provider linking
• Error handling
• Loading states
• Storage clearing

Refactoring Approach:

• Split into multiple contexts:
  • AuthContext - Core auth state only
  • SessionContext - Session management
  • OAuthContext - OAuth providers
  • ProfileContext - User profile data
• Extract services:
  • authService.ts - Auth API calls
  • sessionService.ts - Session operations
  • oauthService.ts - OAuth flows

2. Feed.tsx (958 lines)

Location: client/pages/Feed.tsx

Current Responsibilities:

• Feed filtering logic
• Post rendering
• Comment handling
• Like/unlike logic
• Follow/unfollow logic
• Trending topics
• Sidebar widgets
• Infinite scroll

Refactoring Approach:

• Extract components:
  • FeedFilters.tsx - Filter bar
  • FeedList.tsx - Post list with infinite scroll
  • FeedSidebar.tsx - Sidebar widgets
  • TrendingTopics.tsx - Trending widget
  • SuggestedCreators.tsx - Suggested follows
• Extract hooks:
  • useFeedPosts.ts - Post fetching logic
  • useFeedFilters.ts - Filter state
  • usePostInteractions.ts - Like/comment logic

3. ProfilePassport.tsx (916 lines)

Location: client/pages/ProfilePassport.tsx

Current Responsibilities:

• Profile data fetching
• Achievements display
• Projects showcase
• Social connections
• Following/followers
• Ethos Guild integration
• Arm affiliations
• Degree of connection calculation

Refactoring Approach:

• Extract components:
  • PassportHeader.tsx - Avatar, name, bio
  • PassportStats.tsx - XP, level, streak
  • PassportAchievements.tsx - Badges/achievements
  • PassportProjects.tsx - Project showcase
  • PassportSocial.tsx - Followers/following
  • PassportConnections.tsx - Connection graph
• Extract hooks:
  • usePassportData.ts - Profile fetching
  • useConnectionDegree.ts - Connection calculation

Benefits of Refactoring

• Easier maintenance - Smaller files easier to understand
• Better testability - Can test components in isolation
• Improved performance - Better code splitting opportunities
• Faster development - Changes are localized
• Reduced bugs - Less complexity = fewer edge cases

Implementation Strategy

1. Start with AuthContext (highest impact)
2. Create new smaller contexts/services
3. Migrate logic incrementally
4. Maintain backward compatibility during migration
5. Add tests for each new component
6. Remove old code once fully migrated

Acceptance Criteria

• AuthContext split into 4 smaller contexts
• Feed.tsx split into 6+ components
• ProfilePassport.tsx split into 7+ components
• All functionality still works
• No regressions in user experience
• Code coverage maintained or improved

Impact

• Slower development velocity
• Higher bug risk
• Difficult onboarding for new developers
• Poor code maintainability

---

Issue 4: [P0] Add comprehensive error tracking (Sentry integration)

Labels: infrastructure, P0, monitoring, error-tracking

Problem

Errors are currently logged to console but not tracked or monitored. This means:

• Production errors go unnoticed
• No visibility into user-impacting issues
• Difficult to debug production problems
• No error analytics or trends

Current Error Handling

• console.error() scattered throughout codebase
• Toast notifications for some errors
• No centralized error tracking
• No error grouping or deduplication
• No user context attached to errors

Proposed Solution

Integrate Sentry for comprehensive error tracking and monitoring.

Implementation Checklist

1. Install Dependencies

npm install @sentry/react @sentry/tracing

2. Initialize Sentry

File: client/main.tsx

import * as Sentry from "@sentry/react";
import { BrowserTracing } from "@sentry/tracing";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  integrations: [new BrowserTracing()],
  tracesSampleRate: 1.0,
  beforeSend(event, hint) {
    // Filter out dev environment if needed
    if (import.meta.env.MODE === 'development') {
      return null;
    }
    return event;
  },
});

3. Add Error Boundary

Wrap app with Sentry ErrorBoundary:

<Sentry.ErrorBoundary fallback={<ErrorFallback />}>
  <App />
</Sentry.ErrorBoundary>

4. Set User Context

In AuthContext, add:

Sentry.setUser({
  id: user.id,
  email: user.email,
  username: user.username,
});

5. Add Breadcrumbs

Track important user actions:

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Navigated to profile',
  level: 'info',
});

6. Capture Exceptions

Replace console.error with:

try {
  // risky operation
} catch (error) {
  Sentry.captureException(error, {
    tags: { component: 'Onboarding' },
    extra: { step: currentStep },
  });
  toast.error('Something went wrong');
}

Features to Enable

• Error tracking
• Performance monitoring
• User feedback widget
• Release tracking
• Source maps upload
• Session replay (optional)

Configuration Required

• Environment Variable: VITE_SENTRY_DSN
• Sentry Project: Create project at sentry.io
• Source Maps: Configure upload in build process

Acceptance Criteria

• Sentry SDK installed and initialized
• All uncaught errors tracked
• User context attached to errors
• Important actions logged as breadcrumbs
• Source maps uploaded for readable stack traces
• Error alerts configured
• Team can view errors in Sentry dashboard

Impact

• Unknown production error rate
• Difficult debugging
• Poor user experience (users encounter bugs we don't know about)
• No data-driven prioritization of bugs

---

Issue 5: [P0] Add input validation to all forms

Labels: bug, P0, forms, validation, user-experience

Problem

Forms lack comprehensive client-side validation, leading to:

• Poor user experience (errors only shown after submission)
• Invalid data sent to API
• Confusing error messages
• Higher API error rates

Affected Forms

1. Onboarding Forms

Files: client/components/onboarding/*.tsx

Missing Validation:

• PersonalInfo:
  • Name: Required, min 2 chars
  • Email: Valid email format, required
  • Company: Optional, max 100 chars
• Experience:
  • Skills: Required, at least 1 skill
  • Experience level: Required
• Interests:
  • Primary goals: Required, at least 1
• RealmSelection:
  • Realm: Required selection

2. Profile Editing

File: client/pages/Dashboard.tsx (Profile tab)

Missing Validation:

• Display name: Required, 2-50 chars
• Bio: Optional, max 500 chars
• Website URL: Valid URL format
• Social links: Valid URL formats
• GitHub: Valid GitHub username format

3. Authentication Forms

File: client/pages/Login.tsx

Missing Validation:

• Email: Required, valid format
• Password: Required, min 6 chars (current), should be min 8 chars
• Password confirmation: Must match password

4. Post Composer

File: client/components/feed/PostComposer.tsx

Missing Validation:

• Content: Required, min 1 char, max 5000 chars
• Image URL: Valid URL if provided
• Links: Valid URL format

Recommended Validation Library

Use React Hook Form + Zod for type-safe validation:

npm install react-hook-form zod @hookform/resolvers

Implementation Example

Define Schema (Zod)

// schemas/onboarding.ts
import { z } from 'zod';

export const personalInfoSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters').max(50),
  email: z.string().email('Invalid email address'),
  company: z.string().max(100).optional(),
});

export type PersonalInfoFormData = z.infer<typeof personalInfoSchema>;

Use in Component

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { personalInfoSchema } from '@/schemas/onboarding';

function PersonalInfo() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(personalInfoSchema),
  });

  const onSubmit = (data) => {
    // Data is validated
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('name')} />
      {errors.name && <span>{errors.name.message}</span>}
    </form>
  );
}

Validation Rules by Field Type

Email

• Required
• Valid email format (/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
• Max 255 chars

Password

• Required
• Min 8 chars (update from current 6)
• Must contain: uppercase, lowercase, number
• Max 128 chars

URLs

• Valid URL format
• Must start with http:// or https://
• Optional fields can be empty

Text Fields

• Trim whitespace
• Min/max length based on field
• No HTML injection (sanitize)

Usernames

• Alphanumeric + underscores/hyphens
• 3-20 characters
• Not reserved words

Implementation Checklist

• Install react-hook-form and zod
• Create validation schemas in /client/schemas/
• Update PersonalInfo component
• Update Experience component
• Update Interests component
• Update RealmSelection component
• Update Profile editing form
• Update Login/Signup forms
• Update Post composer
• Add real-time validation feedback
• Add field-level error messages
• Add form-level error summary

Acceptance Criteria

• All forms have client-side validation
• Errors shown in real-time (on blur)
• Clear, actionable error messages
• Form submission disabled until valid
• Visual indicators for invalid fields
• Success indicators for valid fields
• Validation schemas are reusable
• Type-safe form data

Impact

• Poor user experience
• Higher API error rates
• Confusing error messages
• Wasted server resources (invalid requests)

---

Summary

These P0 issues should be addressed in this order:

1. Onboarding progress persistence (30 min fix, high user impact)
2. Error tracking (1 hour setup, critical for monitoring)
3. Form validation (1-2 days, improves UX across app)
4. Stripe integration (2-3 days, enables monetization)
5. Component refactoring (1-2 weeks, ongoing improvement)

Total estimated effort: 2-3 weeks for all P0 items.