Profile Architecture

The profile module follows the domain-based architecture pattern of the BuildAppsWith platform, providing a dedicated set of files for user profile management, builder profile display, and profile-related functionality.

Current Status

Last Updated: Session 11 (May 2025)
Implementation Status: Major refactoring in progress
Type System Status: Partially unified (ValidationTier complete, BuilderProfileData integration ongoing)

Module Structure

The profile module is organized as follows:

/lib/profile/
├── actions.ts                 # Server actions for profile operations
├── api.ts                     # Client-side API functions
├── schemas.ts                 # Zod schemas for validation
├── types.ts                   # UNIFIED TYPE DEFINITIONS (source of truth)
├── utils.ts                   # Utility functions
├── index.ts                   # Barrel exports
└── data-service.ts            # Core profile data operations

/components/profile/
├── builder-profile.tsx            # REFACTORING: Main builder profile component
├── builder-profile-wrapper.tsx   # STANDARDIZED: Profile wrapper with auth
├── builder-profile-client-wrapper.tsx  # Client-side wrapper component
├── client-dashboard.tsx          # Client user dashboard
├── client-profile.tsx            # Client profile display
├── portfolio-gallery.tsx        # STANDARDIZED: Portfolio display
├── portfolio-showcase.tsx        # Portfolio showcase component
├── success-metrics-dashboard.tsx # STANDARDIZED: Metrics display
├── role-badges.tsx              # STANDARDIZED: User role badges (includes SUBSCRIBER)
├── user-profile.tsx             # Generic user profile component
├── profile-auth-provider.tsx    # IMPORT ISSUE: Auth context provider
├── add-project-form.tsx         # Project addition form
├── app-showcase.tsx             # Application showcase
└── ui/                          # UI subcomponents
    ├── profile-header.tsx       # Profile header component
    ├── profile-details.tsx      # Profile details component
    ├── profile-stats.tsx        # Profile statistics
    └── session-booking-card.tsx # Session booking integration

Architecture Principles

1. Type System Unification

COMPLETED: ValidationTier standardization

Source of Truth: /lib/marketplace/types.ts - ValidationTier enum (1, 2, 3)
Conversion Layer: /lib/utils/type-converters.ts provides conversion to trust domain strings
Components Updated: portfolio-gallery, success-metrics-dashboard, role-badges

IN PROGRESS: BuilderProfileData standardization

Source of Truth: /lib/profile/types.ts - BuilderProfileData and BuilderProfileResponseData
Integration: Following Mintlify StandardApiResponse patterns
Elimination: Removed duplicate interface exports from components

2. Component Prop Interface Standards

Following Mintlify component library documentation:

// Base component interface pattern
export interface ProfileComponentProps extends BaseComponentProps {
  profileId?: string;
  userId?: string;
  isPublicView?: boolean;
  profile?: BuilderProfileData;
}

// Specific component extensions
export interface BuilderProfileWrapperProps extends 
  ProfileComponentProps,
  LoadableProps {
  userRole?: UserRole;
  authContext?: ProfileAuthContext;
}

3. API Response Standardization

Following documented StandardApiResponse pattern:

export interface BuilderProfileResponse extends StandardApiResponse<BuilderProfileResponseData> {}

export interface BuilderProfileResponseData {
  // User info (flattened)
  userId: string;
  clerkId?: string;
  email: string;
  name?: string;
  
  // Profile info (unified)
  id: string;
  bio?: string;
  headline?: string;
  validationTier: number; // Uses marketplace enum
  domains: string[];
  topSkills: string[];
  portfolioItems: any[];
  // ... additional component-compatible properties
}

Known Issues & Session 12 Priority

Critical Issues Requiring Immediate Attention

BuilderProfileData Export Breakage

// BROKEN: These imports fail after interface unification
import { BuilderProfileData } from '@/components/profile/builder-profile';

// Files affected:
// - lib/contexts/profile-context.tsx:4
// - lib/utils/profile-form-helpers.ts:3

BuilderProfile Component Parameter Types

8 errors in components/profile/builder-profile.tsx
- Lines 455, 493, 531, 569: Parameter type issues (point, i implicitly 'any')

Property Mapping Issues

// Pages still using old BuilderProfile structure
app/(platform)/builder/[slug]/page.tsx:282
// Missing properties: domains, badges, availableForHire, adhd_focus, etc.

Secondary Issues Identified

Portfolio Gallery: 3 errors at lines 377-379 (ValidationTier conversion edge cases)
Client Profile: 3 errors (Avatar component integration, parameter types)
User Profile: 1 error (ProfileHeader prop interface mismatch)
Profile Auth Provider: 1 error (undefined BuilderProfile reference)

Architectural Gaps Identified

1. Missing Profile Features in Unified Interface

Temporarily Disabled Features (need evaluation for future inclusion):

apps property and AppShowcase component
metrics property and detailed metrics
roles property for multi-role display
isDemo flag for demo account handling
sessionTypes integration

2. Component-Page Integration Issues

Pattern Inconsistency: Some pages create BuilderProfile objects inline instead of using API responses:

// PROBLEMATIC PATTERN
const transformedProfile: BuilderProfileData = {
  id: user.id,
  name: user.name,
  // ... manual transformation
};

// PREFERRED PATTERN  
const profileResponse = await getBuilderProfileById(id);
const profile = profileResponse.data; // Already correctly typed

3. Authentication Integration Gaps

Auth Context Mismatches: Components using deprecated auth hook properties:

// DEPRECATED
const { isLoading, isAuthenticated } = useAuth();

// CURRENT
const { status, isLoaded, isSignedIn } = useAuth();

Session 11 Achievements

Major Accomplishments

ValidationTier Unification Complete
- Established marketplace enum as single source of truth
- Added comprehensive conversion utilities
- Updated all affected components
Profile Type System Foundation
- Eliminated duplicate BuilderProfileData exports
- Standardized on unified interface from /lib/profile/types.ts
- Applied Mintlify documentation patterns
Component Compatibility Improvements
- Fixed property mappings (skills→topSkills, portfolio→portfolioItems)
- Updated wrapper components to use unified types
- Removed data adapter layers
Role Badge Enhancement
- Added SUBSCRIBER user role support
- Fixed role configuration completeness

Error Impact Analysis

Starting Point: ~20 profile component errors
Current State: ~16 profile component errors + 2 new import issues
Net Change: Some errors resolved, some redistributed, some introduced

Future Architecture Considerations

1. Complete Feature Integration

Apps & Metrics Integration: Determine if these should be:

Added to unified BuilderProfileData interface
Kept as separate optional integrations
Removed entirely

2. Component Library Migration

UI Component Standardization: Continue applying Mintlify patterns to:

Profile form components
Profile display components
Portfolio and metrics components

3. API Standardization Completion

Full API Alignment: Ensure all profile-related endpoints follow StandardApiResponse pattern

Implementation Guidelines

Type Usage Standards

// CORRECT: Use unified types
import { BuilderProfileData, ValidationTier } from '@/lib/profile/types';
import { validationTierToString } from '@/lib/utils/type-converters';

// INCORRECT: Don't create local interfaces
export interface BuilderProfileData { ... } // In components

// CORRECT: Convert ValidationTier for trust components
<ValidationTierBadge tier={validationTierToString(profile.validationTier)} />

// INCORRECT: Use numeric tier directly with string-expecting components
<ValidationTierBadge tier={profile.validationTier} />

Component Integration Standards

// CORRECT: Use standardized prop interfaces
interface BuilderProfileWrapperProps extends ProfileComponentProps, LoadableProps {
  userRole?: UserRole;
}

// CORRECT: Direct API response consumption
const profileResponse = await getBuilderProfileById(id);
if (profileResponse.success) {
  const profile = profileResponse.data; // Correctly typed
}

// INCORRECT: Manual data transformation
const adaptedProfile = adaptProfileData(rawProfile);

Session 12 Preparation

Primary Focus: Fix BuilderProfileData import breakage and complete component parameter type resolution. Success Criteria:

Zero import/export errors in profile domain
Less than 10 remaining profile component errors
All components using unified type system
Clean integration between pages and components

​Profile Architecture

​Current Status

​Module Structure

​Architecture Principles

​1. Type System Unification

​2. Component Prop Interface Standards

​3. API Response Standardization

​Known Issues & Session 12 Priority

​Critical Issues Requiring Immediate Attention

​Secondary Issues Identified

​Architectural Gaps Identified

​1. Missing Profile Features in Unified Interface

​2. Component-Page Integration Issues

​3. Authentication Integration Gaps

​Session 11 Achievements

​Major Accomplishments

​Error Impact Analysis

​Future Architecture Considerations

​1. Complete Feature Integration

​2. Component Library Migration

​3. API Standardization Completion

​Implementation Guidelines

​Type Usage Standards

​Component Integration Standards

​See Also

​Session 12 Preparation