@thearchitech.xyz/genome-transformer

@thearchitech.xyz/genome-transformer

Unified Genome Transformation Engine for Architech CLI

A consolidated, extensible package that transforms user intent (genomes) into executable plans through a unified pipeline of specialized transformers.

🎯 Overview

The Genome Transformer consolidates multiple scattered automation systems into a single, clean transformation pipeline. Instead of having transformation logic scattered across different CLI services, everything is centralized in this dedicated package.

Before (Scattered)

• Capability resolution in CLICapabilityResolver
• tRPC detection in TRPCOverrideService
• UI resolution in UIMarketplaceResolver
• Module expansion in ModuleAutoInclusionService
• Validation scattered across multiple services

After (Unified)

• Single GenomeTransformationService orchestrates everything
• Clear transformer pipeline with defined order
• Extensible architecture for new automation
• Centralized error handling and logging

🏗️ Architecture

Transformation Pipeline

INPUT: Genome (Capability or Legacy)
    ↓
[1] CAPABILITY NORMALIZATION (Capabilities → Modules)
    ↓  
[2] MODULE EXPANSION (Add dependencies, expand features)
    ↓
[3] TECH-STACK RESOLUTION (Apply tRPC/SDK overrides)
    ↓
[4] UI MARKETPLACE RESOLUTION (Resolve UI components)
    ↓
[5] PATH REQUIREMENTS EXTRACTION (Extract domains and path needs)
    ↓
[6] FINAL VALIDATION (Validate and prepare)
    ↓
OUTPUT: Resolved Genome (Ready for Execution)

Core Components

GenomeTransformationService

Main orchestration service that coordinates all transformers.

const transformer = new GenomeTransformationService({
  marketplacePath: '/path/to/marketplace',
  logger: console,
  options: {
    enableTRPCDetection: true,
    enableUIResolution: true,
    enableAutoInclusion: true,
    enableCapabilityResolution: true
  }
});

const result = await transformer.transform(genome);

BaseGenomeTransformer

Abstract base class for implementing custom transformers.

class CustomTransformer extends BaseGenomeTransformer {
  readonly name = 'Custom Transformer';
  readonly priority = 10;
  readonly description = 'Custom transformation logic';

  async transform(genome: ProcessedGenome, context: TransformationContext): Promise<ProcessedGenome> {
    // Custom transformation logic
    return genome;
  }
}

Individual Transformers

• CapabilityNormalizer - Converts capability declarations to executable modules
• ModuleExpander - Expands feature modules and adds required dependencies
• TechStackResolver - Applies tech-stack overrides (tRPC, SDK overrides)
• UIMarketplaceResolver - Resolves UI components from appropriate marketplace
• PathRequirementsExtractor - Extracts path requirements from modules for dynamic path generation
• FinalValidator - Performs final validation and preparation for execution

🚀 Usage

Basic Usage

import { GenomeTransformationService } from '@thearchitech.xyz/genome-transformer';

const transformer = new GenomeTransformationService({
  marketplacePath: '/path/to/marketplace',
  logger: console
});

const result = await transformer.transform(genome);
console.log('Transformation result:', result);

Advanced Configuration

const transformer = new GenomeTransformationService({
  marketplacePath: '/path/to/marketplace',
  logger: console,
  options: {
    enableTRPCDetection: true,      // Auto-detect and apply tRPC overrides
    enableUIResolution: true,       // Resolve UI components from marketplace
    enableAutoInclusion: true,      // Auto-add required dependencies
    enableCapabilityResolution: true // Convert capabilities to modules
  }
});

Custom Transformers

import { BaseGenomeTransformer } from '@thearchitech.xyz/genome-transformer';

class CustomTransformer extends BaseGenomeTransformer {
  readonly name = 'Custom Transformer';
  readonly priority = 10;
  readonly description = 'Custom transformation logic';

  canTransform(genome: ProcessedGenome): boolean {
    return genome.modules.some(m => m.id.includes('custom'));
  }

  async transform(genome: ProcessedGenome, context: TransformationContext): Promise<ProcessedGenome> {
    // Custom transformation logic
    return genome;
  }
}

transformer.addTransformer(new CustomTransformer());

📦 Installation

npm install @thearchitech.xyz/genome-transformer

🔧 Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run dev

📚 API Reference

GenomeTransformationService

Constructor

constructor(config: TransformationConfig)

Methods

• transform(genome: Genome): Promise<TransformationResult> - Transform genome
• addTransformer(transformer: GenomeTransformer): void - Add custom transformer
• removeTransformer(name: string): void - Remove transformer
• getTransformers(): GenomeTransformer[] - Get all transformers
• getTransformer(name: string): GenomeTransformer | undefined - Get specific transformer

BaseGenomeTransformer

Properties

• name: string - Transformer name
• priority: number - Execution priority (lower = earlier)
• description: string - Transformer description

Methods

• transform(genome: ProcessedGenome, context: TransformationContext): Promise<ProcessedGenome> - Transform genome
• canTransform(genome: ProcessedGenome): boolean - Check if transformer applies
• validate(genome: ProcessedGenome): Promise<ValidationResult> - Validate genome

Types

TransformationConfig

interface TransformationConfig {
  marketplacePath: string;
  logger: Logger;
  options?: {
    enableTRPCDetection?: boolean;
    enableUIResolution?: boolean;
    enableAutoInclusion?: boolean;
    enableCapabilityResolution?: boolean;
  };
}

TransformationResult

interface TransformationResult {
  originalGenome: Genome;
  resolvedGenome: Genome;
  transformationSteps: TransformationStep[];
  success: boolean;
  error?: string;
  duration: number;
}

TransformationStep

interface TransformationStep {
  transformer: string;
  duration: number;
  modulesCount: number;
  success: boolean;
  error?: string;
}

🎯 Capability-Driven Genomes

The transformer supports both traditional module-based genomes and new capability-driven genomes.

Traditional Genome

const traditionalGenome = {
  version: '1.0',
  project: {
    name: 'my-app',
    framework: 'nextjs',
    structure: 'single-app'
  },
  modules: [
    {
      id: 'adapters/auth/better-auth-nextjs',
      category: 'adapters',
      parameters: {}
    },
    {
      id: 'features/auth/frontend',
      category: 'features',
      parameters: {}
    }
  ]
};

Capability-Driven Genome

const capabilityGenome = {
  version: '1.0',
  project: {
    name: 'my-app',
    framework: 'nextjs',
    structure: 'single-app'
  },
  capabilities: {
    auth: {
      provider: 'better-auth-nextjs',
      frontend: true,
      techStack: true
    },
    payments: {
      provider: 'stripe-nextjs',
      frontend: true,
      backend: true,
      techStack: true,
      database: true
    }
  }
};

The capability-driven approach is much more declarative and easier to understand. The transformer automatically converts capabilities into the appropriate modules.

🔄 Transformation Process

Step 1: Capability Normalization

• Detects if genome is capability-driven
• Converts capability declarations to executable modules
• Maps providers to adapters
• Expands capabilities to feature layers (frontend, backend, tech-stack, database)

Step 2: Module Expansion

• Expands feature modules to include all required layers
• Adds required adapters and dependencies
• Includes marketplace defaults

Step 3: Tech-Stack Resolution

• Detects tRPC usage and applies overrides
• Detects SDK overrides (Better Auth, RevenueCat, etc.)
• Resolves conflicts between overrides

Step 4: UI Marketplace Resolution

• Detects UI framework (Next.js → Shadcn, Expo → Tamagui)
• Loads appropriate UI marketplace manifest
• Resolves UI components for modules that require them
• Validates all required components exist

Step 5: Path Requirements Extraction

• Extracts domain categories from modules (auth, payment, monitoring, etc.)
• Generates required path keys for each domain
• Adds path requirements to genome metadata for marketplace adapter
• Enables dynamic path generation based on actual module needs

Step 6: Final Validation

• Validates all modules exist in marketplace
• Checks for conflicts and duplicates
• Sorts modules by execution order
• Prepares genome for execution

🎉 Benefits

For Users

• Simpler Genome Authoring - Declare capabilities instead of managing modules
• Automatic Resolution - System handles complex module relationships
• Better Error Messages - Clear feedback at each transformation step
• Consistent Results - Same transformation logic every time

For Contributors

• Clear Architecture - Know exactly where to add new automation
• Extensible Design - Easy to add new transformers
• Better Testing - Each transformer can be tested independently
• Centralized Logic - No more hunting for scattered transformation code

For Maintainers

• Single Source of Truth - All transformation logic in one place
• Easier Debugging - Clear transformation pipeline with step-by-step logging
• Better Performance - Optimized transformation order and caching
• Cleaner Codebase - Separation of concerns between CLI and transformation

🤝 Contributing

• Fork the repository
• Create a feature branch
• Implement your transformer
• Add tests
• Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Packages

• @thearchitech.xyz/types - Core type definitions
• @thearchitech.xyz/marketplace - Marketplace modules and blueprints
• @thearchitech.xyz/cli - Main CLI application