rename to core

core/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/types/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>;
+}

core/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>;
+}

core/media/application/ports/ImageServicePort.ts

@@ -0,0 +1,6 @@
+export interface ImageServicePort {
+  getDriverAvatar(driverId: string): string;
+  getTeamLogo(teamId: string): string;
+  getLeagueCover(leagueId: string): string;
+  getLeagueLogo(leagueId: string): string;
+}

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

@@ -0,0 +1,156 @@
+import type { AsyncUseCase, ILogger } from '@gridpilot/shared/application';
+import type { IAvatarGenerationRepository } from '../../domain/repositories/IAvatarGenerationRepository';
+import type { FaceValidationPort } from '../ports/FaceValidationPort';
+import type { AvatarGenerationPort } from '../ports/AvatarGenerationPort';
+import { AvatarGenerationRequest } from '../../domain/entities/AvatarGenerationRequest';
+import type { RacingSuitColor, AvatarStyle } from '../../domain/types/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
+  implements AsyncUseCase<RequestAvatarGenerationCommand, RequestAvatarGenerationResult> {
+  constructor(
+    private readonly avatarRepository: IAvatarGenerationRepository,
+    private readonly faceValidation: FaceValidationPort,
+    private readonly avatarGeneration: AvatarGenerationPort,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(command: RequestAvatarGenerationCommand): Promise<RequestAvatarGenerationResult> {
+    this.logger.debug(
+      `Executing RequestAvatarGenerationUseCase for userId: ${command.userId}`,
+      command,
+    );
+
+    try {
+      // 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,
+        ...(command.style ? { style: command.style } : {}),
+      });
+
+      this.logger.info(`Avatar generation request created with ID: ${requestId}`);
+
+      // Mark as validating
+      request.markAsValidating();
+      await this.avatarRepository.save(request);
+      this.logger.debug(`Request ${requestId} marked as validating.`);
+
+      // Validate the face photo
+      const validationResult = await this.faceValidation.validateFacePhoto(command.facePhotoData);
+      this.logger.debug(
+        `Face validation result for request ${requestId}:`,
+        validationResult,
+      );
+      
+      if (!validationResult.isValid) {
+        const errorMessage = validationResult.errorMessage || 'Face validation failed';
+        request.fail(errorMessage);
+        await this.avatarRepository.save(request);
+        this.logger.error(`Face validation failed for request ${requestId}: ${errorMessage}`);
+        return {
+          requestId,
+          status: 'failed',
+          errorMessage: validationResult.errorMessage || 'Please upload a clear photo of your face',
+        };
+      }
+
+      if (!validationResult.hasFace) {
+        const errorMessage = 'No face detected in the image';
+        request.fail(errorMessage);
+        await this.avatarRepository.save(request);
+        this.logger.error(`No face detected for request ${requestId}: ${errorMessage}`);
+        return {
+          requestId,
+          status: 'failed',
+          errorMessage: 'No face detected. Please upload a photo that clearly shows your face.',
+        };
+      }
+
+      if (validationResult.faceCount > 1) {
+        const errorMessage = 'Multiple faces detected';
+        request.fail(errorMessage);
+        await this.avatarRepository.save(request);
+        this.logger.error(`Multiple faces detected for request ${requestId}: ${errorMessage}`);
+        return {
+          requestId,
+          status: 'failed',
+          errorMessage: 'Multiple faces detected. Please upload a photo with only your face.',
+        };
+      }
+      this.logger.info(`Face validation successful for request ${requestId}.`);
+
+      // Mark as generating
+      request.markAsGenerating();
+      await this.avatarRepository.save(request);
+      this.logger.debug(`Request ${requestId} marked as generating.`);
+
+      // Generate avatars
+      const generationResult = await this.avatarGeneration.generateAvatars({
+        facePhotoUrl: request.facePhotoUrl.value,
+        prompt: request.buildPrompt(),
+        suitColor: request.suitColor,
+        style: request.style,
+        count: 3, // Generate 3 options
+      });
+      this.logger.debug(
+        `Avatar generation service result for request ${requestId}:`,
+        generationResult,
+      );
+
+      if (!generationResult.success) {
+        const errorMessage = generationResult.errorMessage || 'Avatar generation failed';
+        request.fail(errorMessage);
+        await this.avatarRepository.save(request);
+        this.logger.error(`Avatar generation failed for request ${requestId}: ${errorMessage}`);
+        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);
+      this.logger.info(`Avatar generation completed successfully for request ${requestId}.`);
+
+      return {
+        requestId,
+        status: 'completed',
+        avatarUrls,
+      };
+    } catch (error) {
+      this.logger.error(
+        `An unexpected error occurred during avatar generation for userId: ${command.userId}`,
+        error,
+      );
+      // Re-throw or return a generic error, depending on desired error handling strategy
+      throw error; 
+    }
+  }
+
+  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);
+  }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Use Case: SelectAvatarUseCase
+ * 
+ * Allows a user to select one of the generated avatars as their profile avatar.
+ */
+
+import type { AsyncUseCase, ILogger } from '@gridpilot/shared/application';
+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
+  implements AsyncUseCase<SelectAvatarCommand, SelectAvatarResult> {
+  constructor(
+    private readonly avatarRepository: IAvatarGenerationRepository,
+    private readonly logger: ILogger,
+  ) {}
+
+  async execute(command: SelectAvatarCommand): Promise<SelectAvatarResult> {
+    this.logger.debug(`Executing SelectAvatarUseCase for userId: ${command.userId}, requestId: ${command.requestId}, avatarIndex: ${command.avatarIndex}`);
+
+    const request = await this.avatarRepository.findById(command.requestId);
+
+    if (!request) {
+      this.logger.info(`Avatar generation request not found for requestId: ${command.requestId}`);
+      return {
+        success: false,
+        errorMessage: 'Avatar generation request not found',
+      };
+    }
+
+    if (request.userId !== command.userId) {
+      this.logger.info(`Permission denied for userId: ${command.userId} to select avatar for requestId: ${command.requestId}`);
+      return {
+        success: false,
+        errorMessage: 'You do not have permission to select this avatar',
+      };
+    }
+
+    if (request.status !== 'completed') {
+      this.logger.info(`Avatar generation not completed for requestId: ${command.requestId}, current status: ${request.status}`);
+      return {
+        success: false,
+        errorMessage: 'Avatar generation is not yet complete',
+      };
+    }
+
+    try {
+      request.selectAvatar(command.avatarIndex);
+      await this.avatarRepository.save(request);
+
+      const selectedAvatarUrl = request.selectedAvatarUrl;
+      const result: SelectAvatarResult =
+        selectedAvatarUrl !== undefined
+          ? { success: true, selectedAvatarUrl }
+          : { success: true };
+
+      this.logger.info(`Avatar selected successfully for userId: ${command.userId}, requestId: ${command.requestId}, selectedAvatarUrl: ${selectedAvatarUrl}`);
+      return result;
+    } catch (error) {
+      this.logger.error(`Failed to select avatar for userId: ${command.userId}, requestId: ${command.requestId}: ${error instanceof Error ? error.message : 'Unknown error'}`, error);
+      return {
+        success: false,
+        errorMessage: error instanceof Error ? error.message : 'Failed to select avatar',
+      };
+    }
+  }
+}

core/media/domain/entities/AvatarGenerationRequest.ts

@@ -0,0 +1,206 @@
+/**
+ * Domain Entity: AvatarGenerationRequest
+ *
+ * Represents a request to generate a racing avatar from a face photo.
+ */
+ 
+import type { IEntity } from '@gridpilot/shared/domain';
+import type {
+  AvatarGenerationRequestProps,
+  AvatarGenerationStatus,
+  AvatarStyle,
+  RacingSuitColor,
+} from '../types/AvatarGenerationRequest';
+import { MediaUrl } from '../value-objects/MediaUrl';
+ 
+export class AvatarGenerationRequest implements IEntity<string> {
+  readonly id: string;
+  readonly userId: string;
+  readonly facePhotoUrl: MediaUrl;
+  readonly suitColor: RacingSuitColor;
+  readonly style: AvatarStyle;
+  private _status: AvatarGenerationStatus;
+  private _generatedAvatarUrls: MediaUrl[];
+  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 = MediaUrl.create(props.facePhotoUrl);
+    this.suitColor = props.suitColor;
+    this.style = props.style;
+    this._status = props.status;
+    this._generatedAvatarUrls = props.generatedAvatarUrls.map(url => MediaUrl.create(url));
+    if (props.selectedAvatarIndex !== undefined) {
+      this._selectedAvatarIndex = props.selectedAvatarIndex;
+    }
+    if (props.errorMessage !== undefined) {
+      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.map(url => url.value);
+  }
+
+  get selectedAvatarIndex(): number | undefined {
+    return this._selectedAvatarIndex;
+  }
+
+  get selectedAvatarUrl(): string | undefined {
+    const index = this._selectedAvatarIndex;
+    if (index === undefined) {
+      return undefined;
+    }
+    const avatar = this._generatedAvatarUrls[index];
+    if (!avatar) {
+      return undefined;
+    }
+    return avatar.value;
+  }
+
+  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.map(url => MediaUrl.create(url));
+    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 {
+    const base: AvatarGenerationRequestProps = {
+      id: this.id,
+      userId: this.userId,
+      facePhotoUrl: this.facePhotoUrl.value,
+      suitColor: this.suitColor,
+      style: this.style,
+      status: this._status,
+      generatedAvatarUrls: this._generatedAvatarUrls.map(url => url.value),
+      createdAt: this.createdAt,
+      updatedAt: this._updatedAt,
+    };
+
+    return {
+      ...base,
+      ...(this._selectedAvatarIndex !== undefined && {
+        selectedAvatarIndex: this._selectedAvatarIndex,
+      }),
+      ...(this._errorMessage !== undefined && {
+        errorMessage: this._errorMessage,
+      }),
+    };
+  }
+}

core/media/domain/repositories/IAvatarGenerationRepository.ts

@@ -0,0 +1,34 @@
+/**
+ * Repository Interface: IAvatarGenerationRepository
+ * 
+ * Defines the contract for avatar generation request persistence.
+ */
+
+import type { AvatarGenerationRequest } 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>;
+}

core/media/domain/types/AvatarGenerationRequest.ts

@@ -0,0 +1,44 @@
+/**
+ * Domain Types: AvatarGenerationRequest
+ *
+ * Pure type/config definitions used by the AvatarGenerationRequest entity.
+ * Kept in domain/types so domain/entities contains only entity classes.
+ */
+
+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;
+}

core/media/domain/value-objects/MediaUrl.ts

@@ -0,0 +1,46 @@
+import type { IValueObject } from '@gridpilot/shared/domain';
+
+/**
+ * Value Object: MediaUrl
+ *
+ * Represents a validated media URL used for user-uploaded or generated assets.
+ * For now this is a conservative wrapper around strings with basic invariants:
+ * - non-empty
+ * - must start with "http", "https", "data:", or "/"
+ */
+export interface MediaUrlProps {
+  value: string;
+}
+
+export class MediaUrl implements IValueObject<MediaUrlProps> {
+  public readonly props: MediaUrlProps;
+
+  private constructor(value: string) {
+    this.props = { value };
+  }
+
+  static create(raw: string): MediaUrl {
+    const value = raw?.trim();
+
+    if (!value) {
+      throw new Error('Media URL cannot be empty');
+    }
+
+    const allowedPrefixes = ['http://', 'https://', 'data:', '/'];
+    const isAllowed = allowedPrefixes.some((prefix) => value.startsWith(prefix));
+
+    if (!isAllowed) {
+      throw new Error('Media URL must be http(s), data URI, or root-relative path');
+    }
+
+    return new MediaUrl(value);
+  }
+
+  get value(): string {
+    return this.props.value;
+  }
+
+  equals(other: IValueObject<MediaUrlProps>): boolean {
+    return this.props.value === other.props.value;
+  }
+}

core/media/index.ts

@@ -0,0 +1,13 @@
+// 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';
+export type { AvatarGenerationRequestProps } from './domain/types/AvatarGenerationRequest';

core/media/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@gridpilot/media",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./application/*": "./application/*"
+  }
+}

core/media/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": false
+  },
+  "include": ["**/*.ts"]
+}