wip

packages/media/application/ports/AvatarGenerationPort.ts

@@ -0,0 +1,35 @@
+/**
+ * Port: AvatarGenerationPort
+ * 
+ * Defines the contract for AI-powered avatar generation.
+ */
+
+import type { RacingSuitColor, AvatarStyle } from '../../domain/entities/AvatarGenerationRequest';
+
+export interface AvatarGenerationOptions {
+  facePhotoUrl: string;
+  prompt: string;
+  suitColor: RacingSuitColor;
+  style: AvatarStyle;
+  count: number;
+}
+
+export interface GeneratedAvatar {
+  url: string;
+  thumbnailUrl?: string;
+}
+
+export interface AvatarGenerationResult {
+  success: boolean;
+  avatars: GeneratedAvatar[];
+  errorMessage?: string;
+}
+
+export interface AvatarGenerationPort {
+  /**
+   * Generate racing avatars from a face photo
+   * @param options Generation options including face photo and styling preferences
+   * @returns Generated avatar URLs
+   */
+  generateAvatars(options: AvatarGenerationOptions): Promise<AvatarGenerationResult>;
+}

packages/media/application/ports/FaceValidationPort.ts

@@ -0,0 +1,20 @@
+/**
+ * Port: FaceValidationPort
+ * 
+ * Defines the contract for validating face photos.
+ */
+
+export interface FaceValidationResult {
+  isValid: boolean;
+  hasFace: boolean;
+  faceCount: number;
+  confidence: number;
+  errorMessage?: string;
+}
+
+export interface FaceValidationPort {
+  /**
+   * Validate that an image contains exactly one valid face
+   */
+  validateFacePhoto(imageData: string | Buffer): Promise<FaceValidationResult>;
+}

packages/media/application/use-cases/RequestAvatarGenerationUseCase.ts

@@ -0,0 +1,123 @@
+/**
+ * Use Case: RequestAvatarGenerationUseCase
+ * 
+ * Initiates the avatar generation process by validating the face photo
+ * and creating a generation request.
+ */
+
+import type { IAvatarGenerationRepository } from '../../domain/repositories/IAvatarGenerationRepository';
+import type { FaceValidationPort } from '../ports/FaceValidationPort';
+import type { AvatarGenerationPort } from '../ports/AvatarGenerationPort';
+import { AvatarGenerationRequest, type RacingSuitColor, type AvatarStyle } from '../../domain/entities/AvatarGenerationRequest';
+
+export interface RequestAvatarGenerationCommand {
+  userId: string;
+  facePhotoData: string; // Base64 encoded image data
+  suitColor: RacingSuitColor;
+  style?: AvatarStyle;
+}
+
+export interface RequestAvatarGenerationResult {
+  requestId: string;
+  status: 'validating' | 'generating' | 'completed' | 'failed';
+  avatarUrls?: string[];
+  errorMessage?: string;
+}
+
+export class RequestAvatarGenerationUseCase {
+  constructor(
+    private readonly avatarRepository: IAvatarGenerationRepository,
+    private readonly faceValidation: FaceValidationPort,
+    private readonly avatarGeneration: AvatarGenerationPort,
+  ) {}
+
+  async execute(command: RequestAvatarGenerationCommand): Promise<RequestAvatarGenerationResult> {
+    // Create the generation request
+    const requestId = this.generateId();
+    const request = AvatarGenerationRequest.create({
+      id: requestId,
+      userId: command.userId,
+      facePhotoUrl: `data:image/jpeg;base64,${command.facePhotoData}`,
+      suitColor: command.suitColor,
+      style: command.style,
+    });
+
+    // Mark as validating
+    request.markAsValidating();
+    await this.avatarRepository.save(request);
+
+    // Validate the face photo
+    const validationResult = await this.faceValidation.validateFacePhoto(command.facePhotoData);
+    
+    if (!validationResult.isValid) {
+      request.fail(validationResult.errorMessage || 'Face validation failed');
+      await this.avatarRepository.save(request);
+      return {
+        requestId,
+        status: 'failed',
+        errorMessage: validationResult.errorMessage || 'Please upload a clear photo of your face',
+      };
+    }
+
+    if (!validationResult.hasFace) {
+      request.fail('No face detected in the image');
+      await this.avatarRepository.save(request);
+      return {
+        requestId,
+        status: 'failed',
+        errorMessage: 'No face detected. Please upload a photo that clearly shows your face.',
+      };
+    }
+
+    if (validationResult.faceCount > 1) {
+      request.fail('Multiple faces detected');
+      await this.avatarRepository.save(request);
+      return {
+        requestId,
+        status: 'failed',
+        errorMessage: 'Multiple faces detected. Please upload a photo with only your face.',
+      };
+    }
+
+    // Mark as generating
+    request.markAsGenerating();
+    await this.avatarRepository.save(request);
+
+    // Generate avatars
+    const generationResult = await this.avatarGeneration.generateAvatars({
+      facePhotoUrl: request.facePhotoUrl,
+      prompt: request.buildPrompt(),
+      suitColor: request.suitColor,
+      style: request.style,
+      count: 3, // Generate 3 options
+    });
+
+    if (!generationResult.success) {
+      request.fail(generationResult.errorMessage || 'Avatar generation failed');
+      await this.avatarRepository.save(request);
+      return {
+        requestId,
+        status: 'failed',
+        errorMessage: generationResult.errorMessage || 'Failed to generate avatars. Please try again.',
+      };
+    }
+
+    // Complete with generated avatars
+    const avatarUrls = generationResult.avatars.map(a => a.url);
+    request.completeWithAvatars(avatarUrls);
+    await this.avatarRepository.save(request);
+
+    return {
+      requestId,
+      status: 'completed',
+      avatarUrls,
+    };
+  }
+
+  private generateId(): string {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    return 'avatar-' + Date.now().toString(36) + Math.random().toString(36).substr(2, 9);
+  }
+}

packages/media/application/use-cases/SelectAvatarUseCase.ts

@@ -0,0 +1,65 @@
+/**
+ * Use Case: SelectAvatarUseCase
+ * 
+ * Allows a user to select one of the generated avatars as their profile avatar.
+ */
+
+import type { IAvatarGenerationRepository } from '../../domain/repositories/IAvatarGenerationRepository';
+
+export interface SelectAvatarCommand {
+  requestId: string;
+  userId: string;
+  avatarIndex: number;
+}
+
+export interface SelectAvatarResult {
+  success: boolean;
+  selectedAvatarUrl?: string;
+  errorMessage?: string;
+}
+
+export class SelectAvatarUseCase {
+  constructor(
+    private readonly avatarRepository: IAvatarGenerationRepository,
+  ) {}
+
+  async execute(command: SelectAvatarCommand): Promise<SelectAvatarResult> {
+    const request = await this.avatarRepository.findById(command.requestId);
+
+    if (!request) {
+      return {
+        success: false,
+        errorMessage: 'Avatar generation request not found',
+      };
+    }
+
+    if (request.userId !== command.userId) {
+      return {
+        success: false,
+        errorMessage: 'You do not have permission to select this avatar',
+      };
+    }
+
+    if (request.status !== 'completed') {
+      return {
+        success: false,
+        errorMessage: 'Avatar generation is not yet complete',
+      };
+    }
+
+    try {
+      request.selectAvatar(command.avatarIndex);
+      await this.avatarRepository.save(request);
+
+      return {
+        success: true,
+        selectedAvatarUrl: request.selectedAvatarUrl,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        errorMessage: error instanceof Error ? error.message : 'Failed to select avatar',
+      };
+    }
+  }
+}

packages/media/domain/entities/AvatarGenerationRequest.ts

@@ -0,0 +1,218 @@
+/**
+ * Domain Entity: AvatarGenerationRequest
+ * 
+ * Represents a request to generate a racing avatar from a face photo.
+ */
+
+export type RacingSuitColor = 
+  | 'red' 
+  | 'blue' 
+  | 'green' 
+  | 'yellow' 
+  | 'orange' 
+  | 'purple' 
+  | 'black' 
+  | 'white' 
+  | 'pink'
+  | 'cyan';
+
+export type AvatarStyle = 
+  | 'realistic' 
+  | 'cartoon' 
+  | 'pixel-art';
+
+export type AvatarGenerationStatus = 
+  | 'pending' 
+  | 'validating' 
+  | 'generating' 
+  | 'completed' 
+  | 'failed';
+
+export interface AvatarGenerationRequestProps {
+  id: string;
+  userId: string;
+  facePhotoUrl: string;
+  suitColor: RacingSuitColor;
+  style: AvatarStyle;
+  status: AvatarGenerationStatus;
+  generatedAvatarUrls: string[];
+  selectedAvatarIndex?: number;
+  errorMessage?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export class AvatarGenerationRequest {
+  readonly id: string;
+  readonly userId: string;
+  readonly facePhotoUrl: string;
+  readonly suitColor: RacingSuitColor;
+  readonly style: AvatarStyle;
+  private _status: AvatarGenerationStatus;
+  private _generatedAvatarUrls: string[];
+  private _selectedAvatarIndex?: number;
+  private _errorMessage?: string;
+  readonly createdAt: Date;
+  private _updatedAt: Date;
+
+  private constructor(props: AvatarGenerationRequestProps) {
+    this.id = props.id;
+    this.userId = props.userId;
+    this.facePhotoUrl = props.facePhotoUrl;
+    this.suitColor = props.suitColor;
+    this.style = props.style;
+    this._status = props.status;
+    this._generatedAvatarUrls = [...props.generatedAvatarUrls];
+    this._selectedAvatarIndex = props.selectedAvatarIndex;
+    this._errorMessage = props.errorMessage;
+    this.createdAt = props.createdAt;
+    this._updatedAt = props.updatedAt;
+  }
+
+  static create(props: {
+    id: string;
+    userId: string;
+    facePhotoUrl: string;
+    suitColor: RacingSuitColor;
+    style?: AvatarStyle;
+  }): AvatarGenerationRequest {
+    if (!props.userId) {
+      throw new Error('User ID is required');
+    }
+    if (!props.facePhotoUrl) {
+      throw new Error('Face photo URL is required');
+    }
+
+    const now = new Date();
+    return new AvatarGenerationRequest({
+      id: props.id,
+      userId: props.userId,
+      facePhotoUrl: props.facePhotoUrl,
+      suitColor: props.suitColor,
+      style: props.style ?? 'realistic',
+      status: 'pending',
+      generatedAvatarUrls: [],
+      createdAt: now,
+      updatedAt: now,
+    });
+  }
+
+  static reconstitute(props: AvatarGenerationRequestProps): AvatarGenerationRequest {
+    return new AvatarGenerationRequest(props);
+  }
+
+  get status(): AvatarGenerationStatus {
+    return this._status;
+  }
+
+  get generatedAvatarUrls(): string[] {
+    return [...this._generatedAvatarUrls];
+  }
+
+  get selectedAvatarIndex(): number | undefined {
+    return this._selectedAvatarIndex;
+  }
+
+  get selectedAvatarUrl(): string | undefined {
+    if (this._selectedAvatarIndex !== undefined && this._generatedAvatarUrls[this._selectedAvatarIndex]) {
+      return this._generatedAvatarUrls[this._selectedAvatarIndex];
+    }
+    return undefined;
+  }
+
+  get errorMessage(): string | undefined {
+    return this._errorMessage;
+  }
+
+  get updatedAt(): Date {
+    return this._updatedAt;
+  }
+
+  markAsValidating(): void {
+    if (this._status !== 'pending') {
+      throw new Error('Can only start validation from pending status');
+    }
+    this._status = 'validating';
+    this._updatedAt = new Date();
+  }
+
+  markAsGenerating(): void {
+    if (this._status !== 'validating') {
+      throw new Error('Can only start generation from validating status');
+    }
+    this._status = 'generating';
+    this._updatedAt = new Date();
+  }
+
+  completeWithAvatars(avatarUrls: string[]): void {
+    if (avatarUrls.length === 0) {
+      throw new Error('At least one avatar URL is required');
+    }
+    this._status = 'completed';
+    this._generatedAvatarUrls = [...avatarUrls];
+    this._updatedAt = new Date();
+  }
+
+  fail(errorMessage: string): void {
+    this._status = 'failed';
+    this._errorMessage = errorMessage;
+    this._updatedAt = new Date();
+  }
+
+  selectAvatar(index: number): void {
+    if (this._status !== 'completed') {
+      throw new Error('Can only select avatar when generation is completed');
+    }
+    if (index < 0 || index >= this._generatedAvatarUrls.length) {
+      throw new Error('Invalid avatar index');
+    }
+    this._selectedAvatarIndex = index;
+    this._updatedAt = new Date();
+  }
+
+  /**
+   * Build the AI prompt for avatar generation.
+   * We control the prompt completely - users cannot enter free text.
+   */
+  buildPrompt(): string {
+    const colorDescriptions: Record<RacingSuitColor, string> = {
+      red: 'vibrant racing red',
+      blue: 'deep motorsport blue',
+      green: 'racing green',
+      yellow: 'bright championship yellow',
+      orange: 'McLaren-style papaya orange',
+      purple: 'royal purple',
+      black: 'stealth black',
+      white: 'clean white',
+      pink: 'hot pink',
+      cyan: 'electric cyan',
+    };
+
+    const styleDescriptions: Record<AvatarStyle, string> = {
+      realistic: 'photorealistic, professional motorsport portrait',
+      cartoon: 'stylized cartoon racing character',
+      'pixel-art': '8-bit pixel art retro racing avatar',
+    };
+
+    const suitColorDesc = colorDescriptions[this.suitColor];
+    const styleDesc = styleDescriptions[this.style];
+
+    return `Create a ${styleDesc} of a racing driver wearing a ${suitColorDesc} racing suit with matching helmet. The driver should look professional and confident, as if posing for a team photo. Background should be a subtle racing paddock or garage setting. High quality, well-lit, professional motorsport photography style.`;
+  }
+
+  toProps(): AvatarGenerationRequestProps {
+    return {
+      id: this.id,
+      userId: this.userId,
+      facePhotoUrl: this.facePhotoUrl,
+      suitColor: this.suitColor,
+      style: this.style,
+      status: this._status,
+      generatedAvatarUrls: [...this._generatedAvatarUrls],
+      selectedAvatarIndex: this._selectedAvatarIndex,
+      errorMessage: this._errorMessage,
+      createdAt: this.createdAt,
+      updatedAt: this._updatedAt,
+    };
+  }
+}

packages/media/domain/repositories/IAvatarGenerationRepository.ts

@@ -0,0 +1,34 @@
+/**
+ * Repository Interface: IAvatarGenerationRepository
+ * 
+ * Defines the contract for avatar generation request persistence.
+ */
+
+import type { AvatarGenerationRequest, AvatarGenerationRequestProps } from '../entities/AvatarGenerationRequest';
+
+export interface IAvatarGenerationRepository {
+  /**
+   * Save an avatar generation request
+   */
+  save(request: AvatarGenerationRequest): Promise<void>;
+
+  /**
+   * Find an avatar generation request by ID
+   */
+  findById(id: string): Promise<AvatarGenerationRequest | null>;
+
+  /**
+   * Find all avatar generation requests for a user
+   */
+  findByUserId(userId: string): Promise<AvatarGenerationRequest[]>;
+
+  /**
+   * Find the latest avatar generation request for a user
+   */
+  findLatestByUserId(userId: string): Promise<AvatarGenerationRequest | null>;
+
+  /**
+   * Delete an avatar generation request
+   */
+  delete(id: string): Promise<void>;
+}

packages/media/index.ts

@@ -1 +1,12 @@
-export * from './application/ports/ImageServicePort';
+// Ports
+export * from './application/ports/ImageServicePort';
+export * from './application/ports/FaceValidationPort';
+export * from './application/ports/AvatarGenerationPort';
+
+// Use Cases
+export * from './application/use-cases/RequestAvatarGenerationUseCase';
+export * from './application/use-cases/SelectAvatarUseCase';
+
+// Domain
+export * from './domain/entities/AvatarGenerationRequest';
+export * from './domain/repositories/IAvatarGenerationRepository';